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Preface 


Welcome to Macintosh® Programmer’s Workshop 2.0. This preface previews the 
many new features in MPW 2.0, as well as the new hardware and software 
requirements. It also gives the syntax conventions used in the rest of this reference. 


Power tools for Macintosh programmers 


The Macintosh Programmer’s Workshop provides professional software 
development tools for the Apple® Macintosh computer. Briefly, the Macintosh 
Programmer’s Workshop 2.0 consists of the following parts: 


CO MPW Shell (the programming environment) 
MC68xxx Assembler 

Linker 

Make (for tracking file dependencies) 
Resource editor 

Resource Compiler and Decompiler 
Debugger 


Performance measurement tools 
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Commando dialog interface 


The system also includes a comprehensive array of additional tools for creating and 
manipulating text and resource files. The following MPW products are separately 
available: 


= Macintosh Programmer’s Workshop Pascal provides the additional tools, 
interfaces, and libraries you need to develop applications, tools, and desk 
accessories in Pascal. 


= Macintosh Programmer’s Workshop C provides a C Compiler (copyright 
Green Hills Software) along with the interfaces and libraries needed to develop 
applications, tools, and desk accessories in C. 


m MacApp™, the Expandable Macintosh Application. MacApp provides of a set of 
object-oriented libraries that automatically implement the standard Macintosh 
user interface, thus simplifying and speeding up the process of software 
development. MPW Pascal is required for use of MacApp. 


The entire MPW system is outlined in detail in Chapter 1, “System Overview.” 
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The Macintosh Programmer’s Workshop 2.0 provides numerous advantages over 
previous development systems: 


m Integration: The various components of the MP'W system all run within the MPW 
Shell environment, which fully adheres to the standard Macintosh interface. The 
integrated environment enables separately developed applications, called MPW 
tools, to run in the MPW Shell environment. 


= Automated build process: A pull-down menu provides several ways to quickly, 
automatically build or rebuild your programs. You can also automate complex 
builds by using the Make facility and command-language scripts. 


= Command scripting: In addition to menu commands, MPW provides a full 
command language, including Shell variables, command aliases, pipes, and the 
ability to redirect input and output. You can combine any series of commands 
into a command file (or “script”) for fast, accurate, automatic results. 


= Regular expression processing: The editor component of the Shell provides 
powerful search and replace capabilities with regular expressions, which form a 
language for describing complex text patterns. Regular expressions allow you, for 
instance, to restructure complex tables with a single command. 


mw Extensibility: You can create your own integrated tools to run within the Shell 
environment. You can also add your own menu items to the Shell. 


mw Ease of use: The Commando dialog interface gives you immediate on-screen 
access to all of MPW’s versatile options and functions in specialized dialog boxes. 
This interface makes learning easier and faster. You can compose complex 
command lines without referring to the manual. You can create a Commando 
interface for your own tools and scripts as well. 


Taken together, these features add up to a level of integration, power, and ease of use 
not found in any previous microcomputer-based development system. 


What’s new in MPW 2.0 


MPW 2.0 is much faster and easier to use than its predecessor. Many new tools and 
options to existing tools have been added. 


You can quickly and easily build a simple program or desk accessory by using the 
Build menu. The Commando dialog interface makes the numerous command 
options available in dialog boxes, with help text on every option instantly available. 


The four lists below summarize the changes that have been made since the release of 
MPW 1.0 and where you can find more information about these changes. The first list 
describes the changes that are immediately noticeable—the menus. The second list 
mentions changes and additions to the MPW Shell’s command repertoire. The third 
list introduces the new tools and significant changes to existing tools. The final list 
itemizes miscellaneous improvements. 
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New menus 


The first thing you'll notice about MPW 2.0 is that the menus have undergone a 
substantial revision since the release of MPW 1.0: 


Build menu lets you build and execute simple programs entirely by using menus, 
without prior knowledge of many details, such as the command language, 
compiler, linker and make options. You can rebuild complex programs by 
selecting a single menu item, after doing some one-time-only setup work. See 
Chapters 2 and 3. 


Clipboard control has been moved from the Window menu to the Edit menu. 
The Edit menu contains a Show Clipboard item that toggles to Hide Clipboard. 
See Chapter 3. 


Directory menu lets you set the current directory. Use the Build menu to build 
programs that reside in the current directory. See Chapters 2 and 3. 


Enter command has been removed from the Edit menu. It is quicker to click the 
Status panel in the lower-left corner of the active window or simply to press the 
Enter key. See Chapter 4. 


Find options (searching backwards, selection expressions, and so on) are now 
contained in the dialog boxes for Find and Replace, as radio buttons and check 
boxes. A new option, Wrap-Around Search, has been added. There is now more 
room in the Find menu for adding your own customized menu items. See 
Chapter 3. 


Format menu has been replaced by a Format... command in the Edit menu. 
Choose Format to display a dialog box listing all of the available fonts in their 
actual sizes. You can set tabs and auto-indentation, and show invisible settings. 
Use Command-Y to display the Format dialog box. See Chapter 3. 


Mark menu makes it possible to select large portions of a textfile by embedding 
markers. This menu contains the scriptable commands Mark, Unmark, and 
Markers. See Chapter 3 and “Selections” in Chapter 6. 


Menu item styles (for the windows listed in the Window menu) are new. They 
supply more information: A standard check mark indicates the active window; a 
bullet indicates the target window; dirty windows are underlined. 


Window menu (formerly Windows) now contains the new commands 
TileWindows and StackWindows. See Chapter 3 and respective command 
descriptions in Part II. 


New Shell commands 


All of these built-in commands are fully described in Part II: 


Exists: A new built-in Shell command, Exists determines the existence of a file or 
directory. See Part II. 


Mark: This item in the new Mark menu displays a dialog box asking you to supply a 
name for a selected text. See Chapters 3 and 6. 


m™ Markers: This command displays a list of currenty marked texts. See Part II. 


MoveWindow: Use this new command to move a window to a specified h,v 
location. See Part II. 


Newer: This built-in Shell command compares two files to see which was 
modified most recently; the newest filename is displayed. See Part II. 
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Quit: Use this command (the equivalent of the menu item) to exit MPW at the 
conclusion of a script. See Part II. 


Quote: Like Echo, Quote writes its parameters to standard output, except that 
Quote writes parameters that contain special characters, enclosing these special 
characters in single quotation marks. See Part II. 


Revert: This command changes your current window back to its condition at the 
last save. This command is now scriptable. See Part II. 


Shutdown: You can now do a scripted shutdown or reboot of your machine. See 
Part II. 


a SizeWindow: This command sets a window’s size. See Part II. 


n StackWindows: Use this command to arrange open windows in a diagonal 


pattern across the screen. See Part II. 


TileWindows: You can arrange open windows onscreen in a tile pattern so that 
each is fully visible. Then select the window you want and use the zoom box 
control (or its scriptable equivalent, ZoomWindow) to enlarge the window or put 
it back. See Part II. 


8 Undo: The familiar menu item to undo your last edit is now scriptable. See Part II. 


o Unexport: This command removes variable definitions from the export list. See 


Part II. 


Unmark: This item in the new Mark menu displays a dialog box asking which 
marked texts you want to unmark. See Chapter 3. 


Which: This new Shell command displays the full pathname for a given 
file/command/alias. See Part II. 


ZoomWindow: You can instantly enlarge or reduce a window by using this 
scriptable command. It is handy when used in conjunction with TileWindows. See 
Part II. 


New fools 


The tools included with the original MPW 1.0 have been improved in many ways for 
faster performance and increased versatility. In addition to these improvements, the 
following new tools have been developed: 


Assembler: CYCLE and LEAVE directives have been added to the macro 
processor for use with WHILE statements. Performance enhancements are 
expected to increase the speed of macro-intensive assemblies by 40 to 50 percent. 
This improvement has necessitated a change in the format of the LOAD and 
DUMP files. If you have been using this feature, you will need to rebuild all LOAD 
files. See Part II. 


Backup: This versatile new Shell tool is designed primarily to back up project 
directories rather than whole disks. See Part II. 


Commando: This new user interface displays in dialog boxes all the functions, 
parameters, and options for MPW commands. Help for each option is available 
in a special window. See Chapter 4 for an introduction to Commando dialogs. 
You can also use Commando to create a dialog interface for your own MPW tools. 
See Chapter 14. 
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Compare: The new option -v displays differences between two files in a format 
that lets you cut and paste output lines into a source file. See Part II. 


DeRez: The new -i option lets you specify one or more pathnames to search for 
#include files. An -s option lets you search for resource includes. See Part II. 


GetErrorText: This command displays the explanatory text for error messages. 
See Part II. 


GetFileName: Use this command to quickly generate a standard file dialog box. 
See Part II. 


GetListItem: This tool makes it easy to display a selection list in a dialog. See 
Part II. 


Link: This tool now contains the method table optimizer for object Pascal, 
available as the -opt option, thus eliminating any need for the Optimize tool 
distributed with MacApp. See Chapter 10 and Part II. 


MacsBug: MacsBug performance has been enhanced and upgraded. MacsBug 
runs on the Macintosh 512K, Macintosh 512K enhanced, and Macintosh Plus, as 
well as the Macintosh SE and Macintosh I. The MC68881 floating-point 
coprocessor is supported. See Chapter 11. 


m MakeErrorFile: Create error message text with this new command. See Part II. 
m PerformReport: This new utility reports the processor time spent in your source 


code or the ROM on a per-procedure basis. Included in MPW 2.0 is a set of 
performance measurement tools for evaluating the execution speed of your 
programs. See Chapter 12 and Part II. 


Print: This Shell command has been modified to min on all Macintosh 
computers, including the Macintosh SE and Macintosh II, where it uses the new 
ROMs. Three options have also been added. See Part II. 


ProcNames: This new Pascal utility lists a program’s procedure and function 
names, including their nesting level and line numbers. See Part II. 


ResEqual: This command compares two files to determine whether they have 
identical resources. See Part I. 


Resource Tools: Rez and DeRez have some new syntax rules, plus new functions 
and options. See Chapter 8 and Appendix D. 


Search: A new set of five options has been added to increase the versatility of this 
Shell command to search for both matching and non-matching patterns. See 
Part II. 


SetPrivileges: You can now set access privileges to folders shared on an 
AppleShare™ file server. See Part II. 


SetVersion: This is a versatile tool for maintaining version and revision 
numbers. See Part IL. 


Translate: This new command lets you change all occurrences of selected 
characters in a file. It is useful for changing capitalization and for remapping ASCII 
control characters. See Part II. 
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Other new features 
uw Editor capabilities: Several new capabilities have been added: 


CG Command-arrow key combinations move the cursor to the extremes of the 
document. 


Command-Backspace deletes to EOF. 
Command-D opens the selection. 
Command-B clears the selection. 


Oo aaa 


Command-W closes the window. 
O Command-period cancels. 

m -c option: Some commands display a dialog box for a user decision when a 
conflict occurs. The -c option is equivalent to answering “cancel” to any dialog 
box that might otherwise be displayed. In cases where Cancel is clicked in a 
confirmation dialog box, the status return, in MPW 2.0, is nonzero. This feature is 
useful in Shell scripts. For example, the -c option used in a duplicate command 


will abort the script if a conflict should somehow occur. You could then investigate 
the cause of the conflict. 


m Locked files: Locked files can be duplicated, but cannot be renamed or moved. 
m Printing: You can now print from the Finder. 


m Rotate Cursor: Be advised that a change in Rotate Cursor since MPW 1.0 will 
cause old tools to crash when recompiled. 


= Shell scripts: The six command scripts listed here are included to support the 
items in the new menus Directory and Build. You can easily customize these. See 
“Modifying the Build Menu and Makefiles” in Chapter 9. Scripts are also 
individually documented in Part II. 


Q Build 
BuildCommands 
BuildMenu 
CreateMake 


DirectoryMenu 
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SetDirectory 


ws Standard Shell variables: The three new standard Shell variables listed here are 
included in MPW 2.0 to support Commando. See “Variables Defined in the 
Startup File” in Chapter 5. 


OQ {Aliases} 
Oo {Commando} 
Oo {Windows} 
w Status panel: Placing the mouse arrow in the Status panel at the lower-left corner 


of the MPW worksheet changes the panel into a Do It control. Clicking the control 
is equivalent to pressing the Enter key. 
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What you'll need 


This section describes the hardware and documentation you'll need in order to 
develop software with the Macintosh Programmer’s Workshop 2.0. 


Hardware and system requirements 


The Macintosh Programmer’s Workshop 2.0 can generate applications that will run 
on any Macintosh, including the Macintosh II, Macintosh SE, Macintosh Plus, 
Macintosh 128K, Macintosh 512K and 512K enhanced, and Macintosh XL. 


However, the MPW 2.0 system requires, at the minimum, a Macintosh Plus with one 
megabyte of RAM and a hard disk drive, such as the Apple Hard Disk 20. The new 
Workshop will not run on the Macintosh XL, the Macintosh 512K, or Macintosh 512K 
enhanced or on systems without hard disks. MPW 2.0 requires the 128K or 256K 
ROMs; it cannot execute on the older 64K ROMs. A Macintosh II and a SCSI hard disk 
drive is an ideal developmental system for use with MPW 2.0. 


In general, a small RAM cache of about 32K is useful. However, some functions in 
MPW 2.0 may run slower with a RAM cache. Use of MPW with the Switcher™ is not 
recommended. 


MPW software is shipped on 800K disks. Although MPW 2.0 can still read from and 
write to disks that use non-hierarchical filing system disks, MPW’s files must be kept 
on disks that use the hierarchical filing system. Hard disks, when used as boot disks, 
must be hierarchical (HFS) volumes. 


Apple’s Macintosh peripherals, including the LaserWriter® and LaserWriter Plus 
printers and the AppleShare™ file server, are supported. 


System Folder requirements 


Please make sure that you are using the latest versions of the System file and the 
Finder. This software is frequently upgraded by Apple Computer. MPW 2.0 requires 
these minimum system file versions: 


System file 4.1 

Finder 5.5 

Laser Prep 4.0 
ImageWriter® 2.6 
AppleTalk® ImageWriter 3.1 
LaserWriter 4.0 
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These files are available on version 2.0 or later of the System Tools disk, and on the 
latest version of the Printer Installation disk. 
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Documentation 


All programmers will need Volumes I-IV of Inside Macintosh (published by 
Addison-Wesley, 1985), the definitive guide to the Macintosh Operating System and 
user-interface toolbox. Additional features of the Macintosh SE and Macintosh II 
computers are documented in Volume V. If you need to understand and control the 
numeric environment, you'll need the Apple Numerics Manual, a guide to the 
Standard Apple Numeric Environment (SANE™). Finally, you’ll need the 
appropriate documentation for the programming language you'll be using: 


uw Assembly language: Macintosh Programmer's Workshop Assembler 2.0 
Reference. This reference is included in your Macintosh Programmer’s Workshop 
package. You may also need the appropriate microprocessor documentation 
from Motorola. 


m™ Pascal: Macintosh Programmer's Workshop Pascal Reference. This reference is 
available as part of a separate MPW product. 


uw C: Macintosh Programmer's Workshop C Reference. This reference is available 
as part of a separate MPW product. For a guide to the C language itself, you’ll need 
The C Programming Language by B. Kernighan & D. Ritchie, or a similar C 
manual. 


m MacApp: MacApp Programmer's Reference. This reference is part of a separate . 
product, MacApp, the Expandable Macintosh Application, available from 
Apple. The MacApp product also requires MP'W Pascal. 


About this manual 


Part I of this book describes the MPW development system, including the Shell and 
tools. This reference is written for programmers who are already familiar with the 
Macintosh. It outlines the process of building a program, but does not deal with the 
particulars of writing it. Language-specific information is covered in the appropriate 
language references. 


If you are new to MP, see the brief section “Building a Program: An Introduction” 
in Chapter 2. This introduction will take you through MPW’s build process in 
minutes. Chapter 3 introduces the commands available from the menus and 
Chapter 4 covers the basics of using MPW, including features of the Commando 
dialog interface. 


Part II of this manual is a complete alphabetical reference to MPW commands. As 
you become familiar with MPW and no longer need to refer often to the indexed 
chapters of Part I, you may find it convenient to remove Part II and place it in a 
smaller binder for handy reference. 
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Syntax notation 
The following syntax notation is used to describe Macintosh Workshop commands: 


terminal Plain text indicates a word that must appear in the command 
exactly as shown. Special symbols (-, §, &, and so on) must also be 
entered exactly as shown. 


nonterminal Items in italics can be replaced by anything that matches their 


definition. 
[ optional ] Square brackets mean that the enclosed elements are optional. 
repeated... An ellipsis (...), when it appears in the text of this reference only, 


indicates that the preceding item can be repeated one or more 
times. Do not confuse this reference convention with the ellipsis 
command-line character (Option-semicolon), used to invoke the 
Commando dialog interface. 


alb A vertical bar indicates an either/or choice. 
( grouping ) Parentheses indicate grouping (useful with the | and ... notation). 


This notation is also used in the output of the Help command. Gee “The Help 
Command” in Chapter 4.) 


Filenames and command names are not sensitive to case. By convention, they are 
shown with initial capital letters. Terms printed in boldface appear in the glossary. 


About this manual 
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System Overview 


The MPW Shell 


The MPW Shell is an application that provides an integrated, window-based 
environment for program editing, file manipulation, compiling, linking, and 
program execution. The other parts of the Macintosh Workshop—the Assembler, 
compilers, and other tools described below (excepting ResEdit)—operate within the 
Shell environment. These tools can perform input and output to files and to Shell 
windows. . 


The Shell combines a command language, a text editor, and the Commando user 
interface. You can enter commands in any window, or execute them by using menus 
and dialogs. A dialog may include one or more dialog boxes, which may in turn 
contain text boxes, check boxes, radio buttons, and so on. The command language 
provides text editing and program execution functions, including parameters to 
programs, scripting (command file) capabilities, input/output redirection, and 
structured commands. All of the parameters, functions, and options of the 
command language are also available in dialog boxes. 


The MPW Shell integrates the following functional components: 


« Editor for creating and modifying text files. The editor implements normal 
Macintosh-style editing together with scriptable editing commands so that you 
can program the Shell to perform editing functions. (See Chapters 3, 4, and 6.) 


= Command interpreter that interprets and executes commands that you enter in 
a window or read from a file. (See Chapter 5 and Part II.) 


m= User interface that displays dialog boxes providing immediate, graphic access 
to all of MPW’s many functions and options. 


mu Built-in commands that, besides editing commands, include commands for 
managing files without returning to the Finder, for manipulating windows, 
processing variables, program control flow, and more. (See Chapter 5.) 


Window commands 


All work in MPW is done within windows. The following commands are available for 
manipulating windows: 


Close Close a window 

MoveWindow Move window to h,v location on screen 

New Open a new window 

Open Open a window 

Size Window Set a window’s dimensions 

Stack Windows Arrange open windows in a staggered diagonal array 
Target Make a window the target window 

TileWindows Arrange open windows in a tile pattern 

Windows List windows 

ZoomWindow Enlarge or reduce a selected window 
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File management commands 


The MPW Shell provides the following commands for manipulating files and 
directories without having to exit to the Finder: 


Backup 
Catenate 
Delete 
Directory 
Duplicate 
Eject 
Equal 
Erase 
Exists 
Files 
Mount 
Move 
Newer 


NewFolder 


Print 
Rename 
Save 
SetFile 


SetPrivileges 


Unmount 
Volumes 
Which 


Back up folder files 

Concatenate files 

Delete files and directories 

Set the default directory 

Duplicate files and directories 

Eject volumes 

Compare files and directories 

Initialize volumes 

Find out if a file or directory exists 

List files and directories 

Mount volumes 

Move files and directories 

Compare two files to see which was modified most recently 
Create a directory 

Print text files 

Rename files and directories 

Save files in all windows 

Set file attributes 

Set access privileges to folders on file server 
Unmount volumes 

List mounted volumes 

Determine which file (pathname) the Shell will execute 


Editing commands 


Besides the Macintosh’s usual mice-and-menus editing capabilities, a number of 
built-in editing commands are provided. You can use these commands both 
interactively and in command files. Editing commands feature the use of regular 
expressions, a set of special operators that forms a powerful language for defining 
text patterns. See “Pattern Matching” in Chapter 6 for a discussion of regular 


expressions. 


Adjust 
Align 
Clear 
Copy 
Cut 
Find 
Font 
Mark 
Markers 
Paste 
Replace 
Revert 
Tab 
Translate 
Undo 
Unmark 


Adjust lines 

Align text to left margin 

Delete the selection 

Copy selection to the Clipboard 

Copy selection to the Clipboard and delete the selection 
Find and select a text pattern 

Set a window’s font characteristics 

Mark and name a text selection 

List marked selections 

Replace selection with contents of the Clipboard 
Replace the selection 

Revert to saved file 

Set a window’s tab value 

Convert one or more characters 

Undo last edit 

Remove a marker from its text selection 
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Structured commands 


The Shell also provides a number of built-in structured commands. Used mainly in 
command files, these commands provide conditional execution and looping 


capabilities: 
Begin...End 
Break 
Continue 
Exit 

For... 

ae 
Loop...End 


Group commands 

Break from For or Loop 

Continue with next iteration of For or Loop 
Exit from a script 

Repeat commands once per parameter 
Conditional command execution 

Repeat commands until Break 


Other built-in commands 


The MPW Shell also provides a number of other predefined commands: 


AddMenu 
Alert 

Alias 

Beep 
Confirm 
Date 
DeleteMenu 
Echo 
Evaluate 
Execute 
Export 
GetErrorText 
GetFileName 
GetListItem 
Help 
Parameters 
Quit 

Quote 
Request 

Set 

Shift 
ShutDown 
Unalias 
Unexport 
Unset 


Add menu item 

Display alert box 

Define alternate command names 
Generate tones 

Display confirmation dialog box 

Write the date and time 

Delete a user-defined menu or item 
Echo parameters 

Evaluate an expression 

Execute a script without affecting variable scope 
Make variables available to programs 
Display text for system error numbers 
Display a standard file dialog box 
Present file selection list in dialog box 
Display summary information 

Write parameters 

Quit MPW 

Echo parameters, quoting if needed 
Request text from a dialog box 

Define and write Shell variables 
Renumber script positional parameters 
Shut down or reboot machine 

Remove aliases 

Remove variable definition from export list 
Remove Shell variables 
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MPW command scripts 


The items available in the Directory and Build menus use these scripts: 


BuildCommands 


BuildMenu 
BuildProgram 
CreateMake 
DirectoryMenu 
Line 
SetDirectory 


Show build commands 

Create the Build menu 

Build the specified program 

Create a simple makefile 

Create the Directory menu 

Find line number 

Set current directory (from Directory menu) 


MPW tools 


MPW tools are programs that nin within the Shell environment. The tools listed here 
are included with the Macintosh Programmer’s Workshop; several are described in 
more detail in the sections that follow. 


Asm 


Cc 

Canon 
Compare 
Count 
CvtObj 
DeRez 
DumpCode 
DumpObj 
Entab 
FileDiv 
Lib 

Link 

Make 
MDSCvt 


Pascal 
PasMat 
PasRef 
PerformReport 
ProcNames 
ResEqual 
Rez 

RezDet 
Search 
SetVersion 
TLACvt 


MC68xxx Macro Assembler (available as a separate 
product) 

C Compiler (available as a separate product) 
Canonical spelling tool 

Compare text files 

Count lines and characters 

Convert Lisa® object files to MPW object files 
Resource Decompiler 

Dump code resources 

Dump object files 

Convert runs of spaces to tabs 

Divide a file into several smaller files 

Combine object files into a library file 

Link an application, tool, or resource 

Program maintenance tool 

Convert MDS Assembler source (part of the MPW 
Assembler product) 

Pascal Compiler (available as a separate product) 
Pascal program formatter (part of the MPW Pascal product) 
Pascal cross-referencer (part of the MPW Pascal product) 
Generate a report analyzing program performance: 
Display Pascal procedure and functions names 
Compare files on a resource-by-resource basis 
Resource Compiler 

Detect inconsistencies in resources 

Search files for a pattern 

Maintain version and revision numbers 

Convert Lisa TLA Assembler source (part of the MPW 
Assembler product) 
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Assembler 


The Assembler translates MC68000, MC68010, MC68020, and MC68030 assembly- 
language programs into object code. MC68881 floating-point instructions and 
MC68851 memory-management instructions are also supported. The Assembler 
provides powerful macro facilities, code and data modules and entry points, local 
labels, and (optional) optimized instruction selection. Assembly-language 
interfaces are provided to the “Inside Macintosh” libraries. Other libraries and 
example files are also provided. 


The Assembler is provided as a separate product, MPW Assembler, which includes 
the following: 


O translation of MC68000, MC68010, MC68020, and MC68030 assembly-language 
programs into object code 


O support for MC6881 floating-point instructions and MC68851 memory 
management instructions 


O powerful macro facilities, code and data modules, and entry points, local labels, 
and (optional) optimized instruction selection 


O assembly-language interfaces to “Inside Macintosh” routines 
Q conversion tools 


O TLACvt to convert Lisa Workshop Assembler CTLA) source files to MPW 
Assembler source files 


OG MDSCvt to convert Macintosh 68000 Development System (MDS) Assembler 
source files to MPW Assembler source files 


CG sample programs 


Pascal tools 


The Pascal system is provided as a separate product, MPW Pascal, which includes the 
following: 


Pascal Compiler 

Pascal cross reference program (PasRef) 

Pascal source file format program (PasMat) 

Pascal procedure and name program (ProcNames) 


Pascal runtime library 
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Pascal interfaces to the “Inside Macintosh” routines 


O sample programs 


Macintosh Workshop Pascal 2.0 is an improved version of MPW 1.0 Pascal. The 
improvements include: access to C functions and global data, arbitrary-length 
identifiers, object Pascal extensions, support for dynamic array types greater than 
32K, generation of MC68881 code, optional long word data and stack alignment, and 
peephole optimization. 
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C Compiler 


The C Compiler is provided as part of a separate product, MPW C, which includes the 
following: 


O C Compiler 

Q Standard C Library 

Q C interfaces to the “Inside Macintosh” libraries 
O sample programs 


The C Compiler implements the full C language as defined in The C Programming 
Language, by Brian Kernighan and Dennis Ritchie. The usual extensions to this 
definition provide enumerated types and structure assignment, parameters, and 
function results. In addition, Apple extensions provide SANE numerics and 
interfaces to Pascal functions and Macintosh traps. Most Standard C Library 
functions, including character and string processing, memory allocation, and 
formatted input/output, are also provided. Macintosh Workshop C 2.0 supports 
generation of MC68881 code, as well as optional long word data and stack alignment. 


Linker 


The Linker combines object code files into executable programs or driver resources. 
The Linker optionally includes only the code and data modules that are referenced. 
The Linker replaces the code segments in an existing resource file, without disturbing 
other resources in the file. An option directs the Linker to produce a link map as a text 
file. Other options allow the creation of an object module cross reference file or a file 
containing a list of all the unreferenced modules. 


A separate tool, Lib, provides library manipulation. Linking is performed 
automatically for simple programs constructed by using the Build menu. See 
Chapter 10 for details on the use of the Linker with more elaborate programs. 


Make 


The Make tool simplifies software contruction and maintenance. Its input is a list of 
dependencies between files, and instructions for building each of the files. Make 
generates commands to build specified target files, rebuilding only those 
components that are out-of-date with respect to their dependencies. Makefiles are 
generated automatically when you build simple programs from the Build menu. To 
use Make with more elaborate programs, see Chapter 10. 


MPW tools 


ig 


Resource Compiler and Decompiler 


The Resource Compiler (Rez) reads a textual description of a resource and converts it 
into a standard Macintosh resource file. The Resource Decompiler (DeRez) converts 
resources into a textual representation that can be edited in the Shell, and 
recompiled with Rez.You can use DeRez to create Resource Compiler input from any 
existing resource files. Rez and DeRez need templates (type declarations) to define 
resource types. Definitions of the standard Macintosh resource types (‘MENU', 
'STR#', 'ICON', and so on) are provided in two commented text files, Types.r and 
SysTypes.r.Another tool, RezDet, checks resource files for consistency. These 
resource tools are documented in Chapter 8. 


Rez has a new feature in MPW 2.0—an option that permits you to add resources 
without disturbing other resources in the file. 


Commando 


The Commando tool implements the Commando dialog user interface for all other 
MPW tools and commands. Obviously, this is a great convenience for dealing with 
tools offering many interdependent options. Newcomers to MPW will appreciate 
Commando’s instant assistance in building complex command lines. You can also 
use Commando to create specialized dialogs for your own MPW tools and scripts. 


Commando looks in a tool’s or script’s resource fork for a resource of the type cmdo. 
Commando then loads the resource, builds a dialog, handles events, and passes the 
resulting command line back to the Shell for execution .Commando relies on three 
Shell variables to do its work: {Commando}, {Aliases}, and {Windows}. The basics of 
using Commando dialogs are described in Chapter 4. Dialogs utilizing specialized” 
types of dialog boxes are presented with the tools they support in Part II. Chapter 14 
tells you how to create a Commando interface for your own tools and scripts. 


Conversion tools 


Canon is a tool for regularizing the spelling and capitalization of identifiers in source 
files moved from other systems. (In the Macintosh Workshop languages, all 
characters are significant rather than just the first eight as in the Lisa Workshop. In C, 
case also matters.) 


The file Canon.dict contains the correct spelling and capitalization for “Inside 
Macintosh” ROM routines. C programmers, in particular, will find Canon and 
Canon.dict useful. 


Entab is a useful tool for converting space characters and tabs to conform to MPW 
editor or other editor conventions. 


You can look up these conversion tools in Part II. 


Performance measurement tools 


The performance measurement tools enable you to pinpoint where your code is 
spending time. These libraries allow you to sample the program counter, produce a 
file of output data, and analyze that data with a report generator. Advanced 
programmers will find these tools useful for streamlining the execution of their code. 
Chapter 12 is devoted to this subject. 
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Applications 


Applications are stand-alone programs that can execute outside the Shell 
environment A single application, ResEdit, is provided with MPW. It is assumed 
that you already have the Font/DA Mover, which is distributed on the System Tools 
and System Installation disks. Any application can be executed from the MPW 
Shell. 


ResEdit 


ResEdit is an interactive, graphically-based resource editor for creating, editing, and 
copying resources. An interface like that in the MacDraw® application is provided to 
help you design your own fonts. MPW Pascal includes a set of extended Resource 
Manager routines that make it possible to write your own add-on resource editors for 
ResEdit. See Chapter 7 for a thorough explanation of ResEdit. 


Debugger 


An improved MacsBug debugger is provided with MPW 2.0, fully supporting the 
MC68000 and MC68020 processors, as well as the MC68881 floating-point 
coprocessor. MacsBug resides in RAM together with your program. MacsBug allows 
you to examine memory, trace through a program, or set up break conditions and 
execute a program until they occur. MacsBug mins on all Macintosh computers, 
including the Macintosh SE and Macintosh II. See Chapter 11 for instructions on 
using MacsBug and Appendix F for the object file format. 


Special command scripts 


Several special command scripts are provided. These text files contain commands 
that are read by the MPW Shell at startup and shutdown: 


QO The Startup file is a command script containing another script, UserStartup, that is 
run each time you start the MPW Shell. You can use UserStartup to customize 
MPW. The Startup file is discussed in detail in Chapter 5. 


O The Suspend and Resume files are scripts that preserve the state of the Shell 
environment while a stand-alone application is executing. The Quit file saves the 
state of the Shell environment when you exit to the Finder. 


Special command scripts 
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Examples 


In addition to the examples excerpted in this reference work, you'll find numerous 
complete examples in folders included on the MPW distribution disks. 


Sample program files 


Source files are provided for the sample application from Inside Macintosh, as well 
as for a sample MPW tool and a sample desk accessory. Assembly-language versions 
of these programs are contained in the folder AExamples. MPW Pascal and MPW C 
also include Pascal and C versions of the sample files, in the folders PExamples and 
CExamples. The Examples folders also contain instruction files and makefiles for 
building the sample programs. Some of these examples are referred to in Chapter 2, 
in the introduction to building a program. 


Note that these are part of the respective C, Pascal, and Assembler products. 


Command-language examples 


Examples of the use of the MPW command language are provided in the folder 
Examples. Among these are 

Q Addmenu commands for creating user-defined menu items 

O A list of UNIX-oriented aliases 

QO Suggestions for modifying the Startup script 

To learn more about these examples, open the file Instructions in the Examples 


folder. Additional examples are included with each of the MPW commands in 
Part I. The command language is documented in Chapter 5. 
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Overview of MPW files and directories 


Appendix A contains a complete list of all of the Macintosh Workshop 2.0 files. It 
also describes the recommended setup of files on a hard disk. Figure 1-1 shows the 
initial setup of your MPW folders and files on a hard disk. (The Pascal and C systems 
are included.) 


& File Edit Ulew Special 


7) 2) Fl) Bi) 


MPY Shell Startup UserStartup Suspend Resume Quit MPW Help 


je 


SysErrsErr Worksheet Applications Scripts Tools MacsBug 
AExamples Libraries Alnchudes Rincludes ROMMaps AStructMacs 


CExamples CLibraries Cincludes Examples 


PExamples pL raries Pinterfaces 


Figure 1-1 
Setup of MPW folders and files 


For important information about setting up your MPW system, see “Installing the 
System” in Chapter 2. 


Overview of MPW files and directories 
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Chapter 2 


Getting Started 
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This chapter explains how to start using MPW. If you are new to MPW, the tutorial 
“Building a Program: An Introduction,” later in this chapter, will introduce you to 
the extraordinary power and ease of using this environment. 


Installing the system 


Macintosh Programmer's Workshop 2.0 is shipped on five 800K disks: MPW1, 
MPW2, MPW3, MPW Assembler1, and MPW Assembler2. The Pascal and C systems 
occupy another disk each. This section describes how to install the Macintosh 
Workshop files onto any hard disk configuration. MPW 2.0 cannot be installed in its 
entirety on an 800K disk system. 


Appendix A, “Macintosh Workshop Files,” shows the recommended arrangement of 
files on a hard disk. HFS pathname rules are explained in this chapter. 


*» Note: A command script named Startup is executed by the MPW Shell during 
initialization. This file defines several Shell variables, including the variables 
that indicate the location of MPW tools, applications, include files, and 
libraries. Startup must be in the same folder as the MPW Shell. 


Use the Finder to follow these steps: 
1. Create a folder named MPW on the hard disk. 


2. Copy the contents of all five disks to folder MPW. If you have MP'W Pascal or C, 
also copy those disks into the MPW folder. 


3. Move the entire contents of the folder More Tools to the Tools folder; then throw 
away the (now empty) More Tools folder. 


yok 
4. If you have MPW Assembler, move the files Asm, MDSCvt, MDSCvt. Directives, 
TLACvt, and TLACvt.Directives to the Tools folder. If you have Pascal or C, move 
the Pascal and C Compilers (named Pascal and C) into the Tools folder. MPW 
Pascal includes the additional Pascal tools PasMat and PasRef—these should also 
be moved into the Tools folder. 
5. Make sure that the following files are in the same folder as the MPW Shell: 
QO Startup 
Q UserStartup 
© Suspend 
O Resume 
QO Quit 
CO MPW.Help 
OC SysErrs.Err 
By default, the Macintosh Programmer’s Workshop assumes installation in the MPW 
folder as described above. Other configurations are possible but would require some 
changes to the pathnames defined in the Startup file so that the Shell and tools could 
find various files. 
oe 
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Starting up 


“* Note: A small RAM cache (perhaps 32K) is useful when running MPW 2.0. You 
may use larger caches on the Macintosh Plus, Macintosh SE, or Macintosh II, 
with the Assembler and Pascal. MPW C may be used with larger RAM caches on 
systems with more than 1 megabyte of memory. However, some functions in 
MPW 2.0 may run more slowly with large RAM caches. Use of MPW with the 
Switcher is not recommended. 


From the Finder, select and open the MPW Shell icon. The Worksheet window 
(shown in Figure 2-1) will appear with its full pathname in the title bar (for example, 
“HD:MPW:Worksheet”). This window has no close box, and is always present on the 
screen; otherwise it’s just like any other window. 


You can also start the Workshop by double-clicking on any Macintosh Workshop text 
document or tool. 
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Figure 2-1 
Worksheet window 


The menus available from the Shell appear in the menu bar at the top of the screen. 
An explanation of each menu is provided in Chapter 3. You can easily add your own 
menu names. (See Chapter 9.) 


A status panel at the window’s lower-left corner shows the name of the command 
that’s currently executing, or simply “MPW Shell” when you're not executing a 
command. A mouse click on the status panel is equivalent to pressing the Enter key. 


When you first start the Macintosh Programmer’s Workshop, a script called Startup 
executes. The Startup file defines several variables and command aliases (alternate 
command names), this file is further described in Chapter 5. 


Important 
The Startup file must be in the same directory as the MPW Shell. 


Starting up 
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Selecting commands from menus 


In MPW, commands may be built-in commands, scripts (command files), tools, or 
applications, as explained in Chapter 1. 


Several of the built-in commands can be executed by using the File, Edit, Mark, and 
Window menus. The Directory and Build menus are optional, and are normally 
installed by UserStartup scripts. The items in these menus execute scripts (see 
Chapter 3 for details about menus). 


You can add your own menu items to the File, Edit, Find, Directory, and Build 
menus. By using the AddMenu command you can even add your own menus. Each 
user-defined menu item specifies a list of MPW commands that are executed when 
the menu item is selected. See the file AddMenu in the Examples folder for a number 
of ideas for user-defined menus. 


@ File Edit Find Window Mark Directory Build 


Figure 2-2 
MPW menu bar 


Building a program: an introduction 


This section shows how easy it really is to use MPW 2.0 by taking you step by step 
through the process of building an example program. You'll find that the Build menu 
and the Commando dialog boxes make the learning process intuitive and 
comfortable. Even if you’ve never used MPW before, you can immediately use the 
Build menus to build programs. 


MPW’s automated Build menu lets you assemble, compile, and link simple programs 
without studying the command language, the numerous Compiler and Linker 
options, or countless other details. You can use the Build menu to build 

applications, tools, and desk accessories written in assembly language, C, Pascal, 
and Rez or a combination of these languages. You may include resource 
specifications when building programs with these menus. 


The example programs 


In this introduction, three assembly-language programs included with MPW are 
suggested as examples: 


mu Sample: the “Inside Macintosh” sample application 
m Count: an MPW tool that counts characters and lines in a file (see Part II) 


ms Memory: a sample desk accessory that displays the memory available in the 
application and system heaps, and on the boot disk 


Similar program examples are included with MPW C and MPW Pascal. If you are 
primarily interested in programming in one of these languages, be sure to read, in 
the corresponding language reference, the section on the example programs. 


You can routinely rebuild more complex programs by selecting a single menu item. 
There is a smooth transition from the simple builds to the more complex ones. (See 
Chapter 9 for information on how to modify the Build menu and the makefile that it 
creates.) 
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The source files for each of these three assembly-language examples are in the 
“AExamples” folder. For example, the source for Count consists of the files Count.a 
and Stubs.a. A makefile that contains the commands for building all of the examples 
is also provided in the same folder. Instruction files are also provided on the MPW 
disks for each language. If you are new to MPW, we recommend that you start with the 
tutorial that follows rather than with the Intructions file on the disks. At the 
conclusion of this tutorial you will be referred back to the disk instructions. 


Two easy steps 


You can build each of the example programs in two steps, using the Directory and 
Build menus: 


1. Set the current directory. 
2. Build the program. 


Both of these steps are explained below. You can use this section to take MPW ona 
test drive. 


1. Set the current directory. 


Open the Directory menu. The upper half of the menu contains the commands to 
show the current directory and to change it to an arbitrary directory. The lower 
half of the menu lists frequently used directories. 


Directory 


Show Directory 
Set Directory... 


HO:MPW:AEXxamoles: 
HDsMPW:CExamples: 
HO:MPW:Examples: 

HD:MPW:PExamples: 
HO:MPW: 


Figure 2-3 
Directory menu 


Select Show Directory to find out what your current directory is. You'll see the 
alert shown in Figure 2-4. 


The default directory is 


HD:MPW: 


Figure 2-4 
Show Directory alert 
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Click OK to remove the alert. You’re going to build the assembly-language 
program Sample, so you'll need to set the current directory to the directory that 
contains the assembly-language examples. Now open the Directory menu again 
and select the menu item that ends in “AExamples.” (See Figure 2-3.) Selecting 
“AExamples” from the Directory menu runs commands that set the current 
directory. You can check to see if the current directory has been correctly reset by 
selecting the Show Directory menu item again. (The Set Directory... menu item is 
used to add other directories to the list at the bottom of the Directory menu. This 


menu item is explained in “Building a New Program” later in this chapter.) 


2. Build the program. 


Now open the Build menu and select any one of the four Build menu items. 


Build 


Build... 


Figure 2-5 
Build menu 


Create Build Commands... 


Full Build... 
Show Build Commands... 
Show Full Build Commands... 


Each Build item builds your specified program in a slightly different way: 


Build... The program is built automatically, but only files that have been 
modified since you last built the program will be processed. Use 
this item to save time. The Command-key equivalent is 
Command-P. 

Full Build... The program is completely built, ignoring any object files or 
intermediate files that may exist from a previous build. 

Show Build The commands needed to build the program (using just those 

Commands... files affected by modifications since the last build) are displayed 


Show Full Build 
Commands... 


on the worksheet, but not executed. You can then select any or all 
of the commands—or modify them—and then press Enter to 
execute them. 


All the commands needed to completely rebuild the program 
(whether modified since the last build or not) are displayed on 
the worksheet, but not executed. This is a convenient way to see 
all of the commands used in building the program you've 
selected. 
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See “Build Menu” in Chapter 3 for more information on Build menu items. When 
selected, each Build item first displays a dialog box like that in Figure 2-6, requesting 
the name of your program. 


For this tutorial, select Full Build. 


Program Name? 


Figure 2-6 
Program Name? dialog box 


When the Program Name? dialog box appears, type the name of the program you 
want to build (in this case, type “Sample”) and then click the OK button.( Be sure that 
you type the name Sample and not Sample.a. Since you have already set the 
directory to AExamples, you don’t need to indicate that you want to build the 
assembly-language version of Sample. If you give Sample.a as the program name, 
the Build script will attempt to build the source file.) 


The Worksheet window now becomes the frontmost window. The status panel in the 
lower-left corner flashes the name of each operation as it is performed by MPW. 
Each of the MPW commands used by the Full Build script appears on the worksheet as 
it is executed. When the build has finished, your worksheet should look like 

Figure 2-7. 
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Figure 2-7 
Finished Sample build 
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To check your work, press Enter. The Shell then executes the newly built program, 
displaying the text-edit window that Sample creates, as described at the beginning of 
Inside Macintosh. When you quit the Sample program, you are returned to the 
Shell. 


Use the same procedure to build the two other examples in the AExamples folder: the 
tool Count and the desk accessory Memory. For guidance in using these examples, 
consult the file Instructions in the folder AExamples. 


In general, to run a newly built program, select its name (and, in the case of a tool, 
any parameters), and press Enter. If the program you have built is an application, 
your open windows, user-defined menus, and other status information will be saved 
before the program is run. When you quit the application you are returned directly to 
MPW with your previously open windows and menus still displayed. If the program is 
an MPW tool it is run without leaving MPW (be sure to specify any required 
parameters and options). 


When you build a desk accessory by using Build or Full Build, the last line of the Build 
transcript is a command that will run the Font/DA Mover to install the desk accessory 
in the System file. After this installation is complete, the desk accessory will appear in 
the Apple menu. If your Font/DA Mover isn’t in the Applications folder or in 
another directory specified by the {Commands} shell variable, then you should use 
either the Finder or the MPW Duplicate command to move it there. 


If you’re curious about the functioning of any of the Build commands, see Chapter 9 
for more background on the Build process. 


Building a new program 

The Directory and Build menus are convenient to use when writing programs of your 
own. You use slightly different steps for creating a program of your own: 

1. Set the current directory by using the Directory menu. 

2. Type your program. 

3. Select Create Build Commands... from the Build menu. 

4. Select a build item from the Build menu. 


Each of these steps is explained below. 
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1. Set the directory. 


The first step in creating a new program is to set the directory where you want your 
new program to reside. You can select one of the directories that appears in the 
Directory menu, or you can select another directory by using the Set Directory 
menu item. When you select Set Directory from the Directory menu, a standard 
file dialog box, like that in Figure 2-8, appears. 


Select Current Directory: 
MPU 


(1 AENamples 
© Alnciudes 
© Applications 
Q CExamples 


@ Cincludes 

© CLibraries 

© Commando 
© Debuggers 
© Libraries 


Cancel 


Figure 2-8 
Set Directory standard file dialog box 


Select the directory you need. After highlighting the directory you want, click 
“Directory” or “Select Current Directory:” at the top of the dialog box. The new 
directory will then be added to the list of directories on the Directory menu. 


2. Type your program. 


The next step is to create the source files for your program. Select New in the File 
menu. (Remember that assembly-language source filenames should end with 
“a”, C filenames with “.c”, Pascal filenames with “.p”, and Rez filenames with 
“r’.) An empty window now appears and you are ready to type your program. 
Enjoy! 


3. Select Create Build Commands... from the Build menu. 


When you've finished typing in your program, select Create Build Commands 
from the Build menu. You'll see the dialog box shown in Figure 2-9. 


CreateMake Optians 
Program Name Program Type— 
MyProgram | © Application | 
Source and ee Files 


Command Line 
eae MyProgram | 
a 
Create a simple makefile for building an application, tool, or desk Cancel 
accessory. The makefile is for use by the Build menu. G CreateMoke 


Figure 2-9 
CreateMake dialog box 


Building a new program 


Type in the program’s name (without.“.a”, “.c”, or “.p” suffixes) and click a radio 
button to indicate whether you want to create an application, tool, or desk accessory. 
When you click the Files button, another dialog box appears, permitting you to select 
the needed source and library (ending with the *.o” suffix) files. Your program will 
be linked with these files. 


“> Note: It isn’t necessary to indicate the standard library files supplied with MPW. 
Your program will be automatically linked with the appropriate libraries. The 
reference for CreateMake in Part II explains which standard library files will be 
used, 


The Create Build Commands item in the Build menu runs a script that creates a 
makefile with the necessary commands for building programs written in assembly- 
language, C, Pascal, Rez, or a combination of languages. This file is given your 
program’s name with the suffix “.make”. 


** Note: The Build script uses Make to determine the minimum operations 
necessary to bring the program up to date. The Build script looks for its build 
instructions first in program.make (for example, Sample.make). If no such file is 
found, the Build script looks for its instructions in MakeFile. 


4. Select a build item from the Build menu. 


The four build items on the Build menus are variations on a theme. (See Chapter 3 
for an explanation of each item. A brief explanation appears earlier in this chapter 
under step 2 of “Two Easy Steps.”) For now, select Full Build. The rotating beach bail 
cursor appears, indicating that processing has begun. Each step of the build process 
is displayed on the worksheet as it occurs. Any errors will be displayed also, making it 
easy to track down a bit of misplaced syntax. When you have fixed the problem, just 
select Build from the Build menu to quickly rebuild the program. The record of 
previous builds is left on the worksheet. 


See Part II for detailed information on each of the Build menu items. 
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Chapter 3 


Using the Shell Menus 


This chapter describes MPW’s menus and associated dialog boxes. You can build 
simple programs by using the Directory, File, and Build menus. (See Chapter 2.) 
The other menus are used for general editing. Advanced editing capabilities are 
discussed in Chapter 6. 


Features 


The MPW Shell provides the following editing features: 


O Both menu and command-language editing. The menu commands provide the 
usual Macintosh interface. 


O Selecting text by program syntax. You can double-click any of the characters 
( ) f J { } : : . 


to select everything between the character and its mate. (To select text between 
quotes, click the /eft quote.) 


O Selection of large sections of text by embedding markers. Marked selections are 
scriptable; your command files can refer to one or more marked selections. The 
marker commands, Mark and Unmark, are available from the Mark menu. Basic 
interactive use of markers is covered later in this chapter. See Chapter 6 for more. 
detailed information on scripting marked selections. 


O Complete integration of editing functions with the command interpreter. In the 
MPW Shell, there is no separation of “command” and “editor” modes. To the 
Shell, text is text—it is only when you try to directly execute a string of text that the 
Shell decides whether it is a legitimate command or not. 


Q Scriptable commands. Because editing commands are part of the command 
language, you can use them with structured commands and variables to put 
together scripts that define new editing commands. (See Chapter 6.) 


O Regular expressions for matching text patterns. These make possible powerful 
search and replace functions that eliminate the need to make repetitive changes by 
hand. (See Chapter 6.) 


File format 


Shell text is saved as a text-only (TEXT) file. The file contains tab and return 
characters, but no other formatting information. This format is compatible with 
other applications that create text-only files—for example, the Shell can process 
MacWrite® files saved with the Text Only option. When you select the Open 
command, the Shell displays all text-only files in its standard file dialog box, 
regardless of the file creator. 


«* Note: From the Finder, you can open a text file created by another application 
by selecting both the MPW Shell and the text file icons, and then choosing the 
Open command. 


You can display the invisible characters (spaces, tabs, returns, and all other 
“control” characters) with the Show Invisibles menu item. 


A file’s tab setting, font setting, selection, window settings, auto-indent state, 
invisibles state, and markers are saved with the file, in its resource fork. 
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Menu commands 


In general, the menu interface is the familiar Macintosh implementation. There are a 


few differences and extensions, which are detailed in the following sections. (It’s 
assumed that you are already familiar with standard Macintosh editing techniques.) 


All menu commands act on the active (that is, the frontmost) window. 


“* Note: Many menu items (including several items in the File menu and all user- 
defined items) are disabled when you are running tools, scripts, applications 
and other commands. This convention prevents you from closing windows that 


the command may be reading, and from trying to mun another command at the 
same time. 


Apple menu 
About the MPW Shell Displays version and copyright information. 


File menu 
Each of the items in the MPW File menu is described below. 


New... 
Open... x0 
Dpea Selec Yon 


Close 
Save *S 
Save as... 

Save a Copy... 
Revert to Saved 


Page Setup... 
Print Window 


Figure 3-1 
File menu 


Menu commands 
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Open... 


Open Selection 


Close 


Save 


Save as... 


Displays the New dialog box, shown in Figure 3-2. The MPW New 
dialog box allows you to enter a name and select a directory 
location for the document. The Command-key equivalent is 
Command-N. 


© AExamples 

CG Alnctudes 

© Applications Bi 
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© Cinciudes 
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Open document 


Figure 3-2 
New dialog box 


Displays an Open dialog box (similar to that in Figure 3-2) that 
allows you to open any TEXT file on the disk. When you open a 
file for the first time, the selection point is at the top of the file. 
When you open the file again, it reappears in the same state in 
which it was saved; that is, the previous selection or insertion 
point is preserved unless the file has been modified outside the 
editor. The Command-key equivalent is Command-O. 


Note: If you try to open a document that’s already open in 
another window, that window will be brought to the front. 


If you select a document name within a window, the Open 
Selection command automatically displays the selected name. 
This is a useful shortcut when you have already displayed 
filenames on the screen, with the Files command for 
example—you can then select a filename and open a file 
directly, bypassing the usual Open dialog box. Variable and 
command substitution occur on the selection. The 
Command-key equivalent is Command-D. 


Closes the active (frontmost) window. The Command-key 
equivalent is Command-W. 


Saves the active window under its current name, without closing 
it. This menu item is dimmed if the contents of the window 
haven’t been modified since it was last saved. The Command-key 
equivalent is Command-S. 


Displays a Save As dialog box, allowing you to change the name 
and directory location of the active window. Saves the current 
contents of the window as the “Save As” file, and allows you to 
continue editing the new file. The old file is closed without 
saving, under its original name. 
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Save a Copy... 


Revert to Saved 


Page Setup... 


Print Window 


Quit 


Saves the current state of the active window to a new file on the 
disk. You can then continue editing the old file. 


Throws away any changes you have made since you last saved the 
active window. 


Displays the standard Page Setup dialog box. 


Prints either the entire active window or the selection in the 
active window. If any text is selected in the active window, that 
text is printed. If no text is selected, the entire contents of the 
window (that is, the entire file) are printed. 


The Print menu item doesn’t display the usual Print dialog box. 
Instead, you can specify printing parameters by setting the Shell 
variable {PrintOptions}, described in Chapter 5. Printing 
options include the number of copies to print, which pages to 
print, print quality, font and font size, headings and tide, 
borders, and printing the pages in reverse order (for use with the 
LaserWriter). See the description of the Print command in Part II 
for a complete specification of these options, or enter the 
command Help Print to see a summary. 


Technical note: The Print Window menu item executes the Shell 
command 


Print (PrintOptions} "{Active}" 0 
22 "(Worksheet)" 


Print Selection executes the same command, with .§ added after 
the name of the active window. 


Important: For the Print command to work properly, you must 
install the printer drivers available on version 1.0 or later of the 
Printer Installation disk. Use the Chooser Desk Accessory from 
the Apple menu to specify which printer to use. Use the Page 
Setup dialog box to specify paper size, orientation, and 
reductions or enlargements. 


Returns to the Finder, first allowing you to save the current state 
of all open files. The Command-key equivalent is Command-Q. 
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Edit menu 


See “Editing With the Command Language” in Chapter 5 for more information on 
using the scriptable forms of the commands on this menu. 


Select All XA 
Show Clipboard 


Align 
Shift Left xf 
Shift Right %] 


Figure 3-3 
Edit menu 


Undo 


Cut 


Copy 


Paste 


Clear 
Select All 


Show Clipboard 


Undoes the most recent changes to text in the active window (but 
not changes to resources such as font or tab settings). You can 
select Undo again to redo changes. The Command-key 
equivalent is Command-Z. _ 


Copies the current selection in the active window to the 
Clipboard, and then deletes it from its original location. The 
Command-key equivalent is Command-X. 


Copies the current selection in the active window to the 
Clipboard. The Command-key equivalent is Command-C. 


Replaces the contents of the current selection in the active 
window with the contents of the Clipboard. The Command-key 
equivalent is Command-V. 


Deletes the current selection in the active window. 


Selects the entire contents of the active window. The 
Command-key equivalent is Command-A. 


Opens a window displaying the contents of the Clipboard, if 
any. 
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Format... 


Tabs 


Auto Indent 


Show Invisibles 


Displays the Format dialog box offering a selection of fonts and 
sizes. The Command-key equivalent is Command-Y. This dialog 
box is shown in Figure 3-4. 


Chicago {J Auto Indent 
Courier C) Show Inuisibles 
Geneva 


Helvetica 


Monaca 


Figure 3-4 
Dialog box of the Format menu Item 


Sets the number of spaces that a tab character will signify for the 
active window. (The default tab setting is set by the Shell variable 
{Tab}, described in Chapter 5.) 


Toggles Auto Indent on and off. When Auto Indent is on, 
pressing Return lines up text with the previous line. (A check mark 
indicates that Auto Indent is on.) 


Displays the invisible characters as follows: 


Tab A 
Space 0 
Return a 


All other control characters é 


The rest of the dialog box consists of a selection of the fonts installed in your System 
file. Available font sizes are displayed in the dialog window. 


“* Note: Selecting a font and font size affects the entire active window, not just the 
current selection in that window. 


Align Aligns the currently selected text with the top line of the selection. 


Shift Left, These commands move the selected text left or right by one tab stop. 

Shift Right | You can thus move a block of text while maintaining indentation. Shift 
Left adds a tab at the beginning of each line. The Command-key 
equivalent is Command-[. Shift Right removes a tab, or the equivalent 
number of spaces, from the beginning of each line. The Command- 
key equivalent is Command-]. If you hold down the Shift key while 
using these menu items, the selection will be shifted by one space, 
rather than by one tab. 
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Find menu 


Each of the items in the Find menu is described below. 


Find... eF 
Find Same 6 
tind Selectian ost 
Display Selection 


Replace... sR 
Replace Same XT 


Figure 3-5 
Find menu 


Find... 


Find Same 
Find Selection 
Display Selection 


Replace... 


Replace Same 


Displays a Find dialog box and finds the string you specify. By 
default, the Editor searches forward from the current selection 
in the active window (and does not wrap around). The 
Command-key equivalent is Command-F. This dialog box is 
very similar to the Find-and-Replace dialog box described 
below; the explanation of the radio controls and check boxes 
applies to both dialog boxes. 


Repeats the last Find operation, on the active window. The 
Command-key equivalent is Command-G. 


Finds the next occurrence of the current selection in the active 
window. The Command-key equivalent is Command-H. 


Scrolls the current selection in the active window into view. 


Displays the Find-and-Replace dialog box shown in Figure 3-6 
and explained below. The Command-key equivalent is 
Command-R. 


Repeats the last Replace operation. The Command-key 
equivalent is Command-T. 


Find what string? 


@ Literal (] Case Sensitive 


© Entire Word (J Seerch Backwards 
O Selection Expression 


Figure 3-6 
Dialog box of the Replace menu item 
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The operation of this dialog box is very similar to that of the Find dialog box, except 
that selected strings can be located and replaced with a different string throughout a 
file. Both dialog boxes have three radio buttons offering you one of three mutually 
exclusive options: 


Literal Finds the exact string (without regard for case) that you specify, 
wherever it may appear, even if part of other words or 
expressions. 

Entire Word Finds the specified string only when it occurs as a single word. 


To the Editor, a word is composed of the characters a—z, A-Z, 
0-9, and the underscore character ( _ ). (You can change these 
default values by redefining the Shell variable {(WordSet}—see 
“Predefined Variables” in Chapter 5.) 


Selection Enables the full selection and regular expression syntax, as used 

Expression with the command language and described in Chapter 6. These 
expressions allow powerful selection and pattern matching 
capabilities that use a special set of metacharacters introduced 
below. 


Any combination of the three check boxes may be selected: 


Case Sensitive Searching is normally case insensitive; selecting this menu item 
specifies case-sensitive searching. (it does this by setting the 
Shell variable {CaseSensitive}—see “Variables Defined in the 
Startup File” in Chapter 5.) 


Search Backward Search backward, from the current selection to the beginning of 
the file. (Normally, searching is forward, and stops at the end of 


the file.) 
Wrap-Around Searches forward to the end of file, then wraps around and 
Search searches from the beginning of the file to the location of-.the 


cursor when the search was initiated. (Direction of search is 
reversed if Search Backward is also checked.) 


«* Note: For Find and Find-and-Replace operations, a beep indicates that the 
selection was not found. 
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Selection expressions 


When the Find-and-Replace dialog’s “Selection Expression” switch is selected, you 
can use a special set of expression operators to specify selections and text patterns. 

This section introduces a commonly used subset of these selection operators. Many 
more capabilities are available, and a full discussion can be found in Chapter 6. 


Selection by IIne number: A number given by itself specifies a line number. In the 
figure below, for example, the command selects line number 30 in the active 
window. 


Find what selection expression? 


O Literal (CJ Case Sensitive 


© Entire Word C0 Search Backwards 
@ Selection Expression CJ Wrap-fround Search 


Figure 3-7 
Selection by line number 


Wildcard operators: The same wildcard operators used in filename generation can 
also be used to specify text patterns for Find commands: 
? Any single character (other than Return). 


= Any string of 0 or more characters, not containing a Return. (To 
get the = character, press Option-X.) 


(characterList] Any character in the list. 


Note: The brackets must be typed; they don’t indicate an 
optional syntax element. 


[—cha@racterList] Any character not in the list. (To get the — character, press 
Option-L.) 


These pattern matching operators are part of a larger set called regular expression 
operators. A regular expression consists of literal characters and/or regular 
expression operators, and must be enclosed in slashes (/.../). The figure below 
shows an example. 


Find what selection expression? 


/\nit=/| 


© Literal CO Case Sensitive 


© Entire Word CJ Search Backwards 
@ Selection Expression CJ Wrap-fround Search 


(ring | 


Figure 3-8 
Example of a regular expression 
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This command finds and selects any string that begins with “init” and is followed by 
any characters other than a return. Figure 3-9 shows the result of this command. 


2—°*—EESSSSS3 HD:MPwW:PExamples:Sample.p 
TEPaste(textH) ; 


END; 
oleerConmend: TEDelete(textH) ; 
END; (of item CASE) 
EMD; (of editID) 


EMD; (of menu CASE) {to indicate completion of commend ,) 
Hilitetienu( 0); {call Menu Manager to unhighlight senu 
(highlighted by HenuSelect)) 
EMD; (of DoCommeand) 


BEGIN {main progres) 
f@elratislisatien 
UnLoedSeg(@_DataInit) ; (remove data initialization code befor 
TnitGraf(QthePort) ; (initialize QuickDraw) 
InitFonts; . {initialize Font Manager) 
FlushEvents(everyEvent, 0); {call 0S Event Mor to discard 


Figure 3-9 
Text selected with the Find command 


As mentioned, many additional Find and Replace capabilities are available. ee 
Chapter 6.) In the command language, the Find and Replace functions are 
performed by the Find and Replace commands. There’s also a tool named Search 
(described in Part ID that can search through a list of files for the occurrence of any 
text pattern. 


Window menu 


The upper half of the Window menu contains the two commands Tile Windows and 
Stack Windows; the lower half lists all open windows, as shown in Figure 3-10. 
Selecting a window from the menu brings that window to the front, that is, 
superimposes it over anything else on your display. A check indicates that the 
window is currently the “active” window, that is, the frontmost. A bullet (¢) indicates 
that the window is the “target” window, that is, the second to the front. Underlining 
indicates that a window contains changes that have not yet been saved. 


Window 
Tila Windows 
Stack Windows 


/HD :MPIUW:Worksheet 


Figure 3-10 
Window menu 


Tile Windows Use this command to arrange windows in a tile pattern on the 
screen so that each window’s contents are visible. Then choose a 
window and click its zoom box to enlarge it to full screen size. See 
Part II for information on using TileWindows in scripts. 


Stack Windows Use this command to arrange windows in a diagonally staggered 
pattern on your screen. This is the “open file folder” way to see 
several windows at once. See Part II for a description of the 
scriptable version, StackWindows. 


Worksheet The Worksheet window always appears first in the Window menu. 
The menu item lists the full pathname of the worksheet. 


Menu commands 


Mark menu ‘2 


A marker is a text selection that has been given a name. Markers are useful for 
navigating within a window, and they can simplify many selection expressions. The 
upper half of the Mark menu contains the commands Mark and Unmark and the lower 
half lists all existing markers. To jump to the location of a marker you simply choose 
the name of the marker you want from the Mark menu, shown in Figure 3-11 (only the 
marker “Here” has been created in this example). 


Markers can be created and used both interactively, via the Mark menu, and 
programmatically, via the Shell commands Mark, Unmark, and Markers. For a 
detailed discussion of the syntax, characteristics, and programmatic use of markers, 
see Chapter 6 and Part II. 


Mark... 3M 
Unmark... 


Figure 3-11 
Mark menu 


Mark... To create a new marker interactively, first select the text you want to 
mark, then choose “Mark” from the Mark menu. A dialog box like that 
in Figure 3-12 appears, asking for the name you want the marker to 
have. The editable text field in the dialog box is initialized to the first 
word (that is, whatever you would select by a double-click) in the oe 
selection. If you click Cancel in the dialog box, the selection is : 
unchanged and no new marker is created. If you click OK a new marker 
is created with the specified name and the new marker’s name is added 
to the list of marker names displayed by the Mark menu. 


Mark the selection with what name? 


Figure 3-12 
Mark dialog box 


If you try to create a new marker using the name of an already existing 
marker, a dialog box will appear, giving you the chance either to delete 
the old marker and add the new (OK), or to forget about adding the new 
marker (Cancel). 
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Unmark... 


If you choose the Unmark menu item from the Mark menu, you'll see a 
dialog box, like that in Figure 3-13, that contains a list of currently 
defined markers and the two buttons Delete and Cancel. If a marker is 
currently selected, its name is highlighted in the marker list. You can 
select any number of marker names from the list. If you click Delete, 
every marker selected in the list is deleted. If you click Cancel, the 
selection remains unchanged and no markers are deleted. 


Delate which markers? 


Figure 3-13 
Unmark dialog box 


Directory menu 


The Directory menu, shown in Figure 3-14, lets you display and easily change the 
name of the default (current) directory. The Directory menu is implemented by the 
scripts DirectoryMenu and SetDirectory, that you can modify to suit your own needs. 


Directory 
Show Directory 
Set Directory... 


HD :MPW:AEXamples: 
HD :MPW:CExamples: 
HD :MPW:PExamples: 
HD :MPU: 


Figure 3-14 
Directory menu 
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Show Directory 


Set Directory... 


<DirectoryName> 


Warning 


An alert box displays the name of the current default 
directory. Click OK to make the alert go away. 


Sets the default directory. When you select this menu item the 
Set Directory... dialog box, shown in Figure 3-15, appears, 
providing interactive selection of the default directory. Your 
selection is then added to the Directory menu. 


Select Current Directory: 
& MPW 


Ca AExamples 
© Alnctudes 
© Applications 
© CExamples 


© Cincludes 

© CLibraries 

© Commando 
© Debuggers 
© Libraries 


Figure 3-15 
Dialog box of the Set Directory menu item 


Selecting a directory name makes this directory the new 
default directory. 


As you select various default directories, using either the Set 
Directory... menu item or the SetDirectory command, each 
is added as a separate menu item to make it easy to return to 
that directory in the future. The UserStartup script creates 
menu items for each of the Examples folders in the MPW 
directory, and for the default directory at the time the 
UserStartup script is run. You can add your own favorite 
directories by modifying UserStartup. 


Directory names should not contain any of these special characters: 


2 : A 


< / ( 


These characters have special meanings when they appear as menu items. 
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Build menu 


The Build menu, shown in Figure 3-16, has two primary purposes. First, it is used to 
create a makefile containing the commands needed to build a program. Second, it is 
used either to build a specified program or to display the commands needed to do 
the build. Use of the Build menu is demonstrated in Chapter 2, “Building a Program: 
An Introduction.” 


Build 


Build... 
Full Build... 


Figure 3-16 
Build menu 


Create Build 
Commands... 


Create Build Commands... 


Show Build Commands... 
Show Full Build Commands... 


%8 


Creates a makefile containing the build commands for a specified 
program. When you click Create Build Commands..., the 
CreateMake dialog box appears. (See Figure 3-17.) You can then 
enter the program name and select its type (that is, Application, 
Tool, or Desk Accessory—make sure that you do not include a 
“a”, “-c”, or “.p” suffix to the program name). 


Click the Files button to select the program’s source and library 
files. (MPW libraries are automatically linked; certain special 
libraries you may require may not be automatically linked. See 
CreateMake in Part II.) If the program’s name is program, a new 
makefile, called “program.make’”, is created. The makefile will 
contain simple build commands from the program. 


Be sure to run Create Build Commands whenever you create 
additional source or library files for a program. Answering the 
CreateMake dialog box generates a new set of rules in 
program.make that includes the new source files. 


CreateMake Options 


Program Name (an Type 


= 
| © Application | 


Source and Library Files : OTool H 
joo | 


Command Line 

a MyProgram | 
Help Cancel 

Create a simple makefile for building an application, tool, or desk 


accessory. The makefile is for use by the Build menu. 4 "i temMake | 


Figure 3-17 
CreateMake dialog box 
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When you select from the Build menu, one of the following four Build items, a dialog 
box appears, asking for the name of the program you want to build. 


Program Name? 


Figure 3-18 
Program Name? dialog box 


Type the name and click the OK button. The commands used to build the program, 
plus any error messages, will then be displayed on the worksheet. 


Build... The program is built automatically, but only files that have been 
modified since you last built the program will be compiled. Use 
this item to save time. The Command-key equivalent is 
Command-P. 


Full Build... The program is completely built, ignoring any object files or 
intermediate files that may exist from a previous build. 

Show Build == = The commands needed to build the program (for just those files 

Commands affected by modifications since the last build) are displayed on 


the worksheet, but not executed. You can then select any or all of 
the commands—or modify them—and press Enter to execute 
them. 


Show Full Build All the commands needed to completely rebuild the program 

Commands (whether modified since the last build or not) are displayed on 
the worksheet, but not executed. This is a convenient way to see 
all of the commands used in building the program you've 
selected. 


Each of the four Build menu items uses the MPW tool Make to determine which 
Operations are necessary to build the program. The Makefile “program.make” is 
created by the Create Build Commands... menu item (described above). If you have 
not used this item—that is, if program.make doesn’t exist—MPW will use the file 
MakeFile. (See Chapter 10.) 


User-defined menus 


You can define your own menu commands with the AddMenu command, described 
at the end of Chapter 5. These commands can be appended to existing menus, or 
you can create new menus. 
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Chapter 4 


Using MPW: The Basics 


This chapter introduces the basic conventions for manipulating files, editing text, 
executing commands, and responding to dialogs in the Macintosh Programmer’s 
Workshop. You can easily enter all commands, command options, and parameters 
by using the menus and dialog boxes. The basics for directly typing commands in a 
window are also introduced. A full discussion of command scripting can be found in 
Chapter 5. See Chapter 2 for an introduction to building a simple program, using 
examples contained in the “Examples” folders. 


Editing 


Basic editing functions are available as menu commands. You can open a file with 
the Open command, or by selecting its name on the screen and choosing the Open 
Selection command (Command-D) from the File menu. You can select and edit text 
with the usual Macintosh editing techniques, using menu commands to cut, copy, 
and paste selected text. The menu commands are described in Chapter 3. 


Editing with MPW is unique in that most menu functions are duplicated in the Shell 
command language. Editing and other command-language functions are fully 
integrated—you enter and execute editing commands just like any other commands. 
Editing commands are entered in the active window (the frontmost window), but 
they act on text in the target window (the second window from the front), or 
another window that you explicitly name. The command language lets you produce 
scripts of editing commands: You can save any series of commands as a normal text 
file, and execute the file by simply entering the filename. Command-language 
editing is discussed further in “Editing With the Command Language” in Chapter 5. 


Entering commands 


All MPW commands and their options can be selected from menus and dialog 
boxes. Generally, this interactive method of command selection is the easiest. You 
can immediately execute commands selected from menus and dialog boxes, or you 
can use the dialog boxes to compose complex command lines that can then be 
copied to a command script. 


The dialog boxes for MPW commands are generated by the Commando user 
interface (described in the last section of this chapter). Besides the usual Macintosh 
dialog boxes, Commando provides several new forms and controls to handle the 
special requirements of MPW tools. For example, dialogs for commands with many 
options may have several nested dialog boxes. Which dialog boxes are actually 
displayed may vary according to dependency relations between the particular 
options you may have selected. Some of the specialized dialog controls are 
introduced at the end of this chapter. Other unique dialog boxes are shown in Part II 
of this reference with their respective commands. A detailed discussion of all the 
elements of Commando dialogs can be found in Chapter 14, which explains how to 
create a Commando interface for your own tools and scripts. 


Of course, you can also type commands directly in any window as a series of words 
separated by spaces or tabs. 
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Typing commands in a window 


By default, command output and any error messages appear in the window 
immediately below the executed command line. Commands are not case sensitive. 
You can have multiple open files, and you can enter commands in any window. 


The simplest commands consist of the command name only. For example, type the 
command 


Date 


and press the Enter key (without pressing Return first—that is, the insertion point 
must be on the same line as the command when you press Enter). This command 
outputs the date and time: 


Tuesday, July 14, 1987 7:12:00 AM 

Commands can have options. For example, 

Date -d 

The -d option tells the Date command to list the date only, 


Tuesday, July 14, 1987 


Commands typed into a window are referred to as standard input. When the results 
of the command(s) are then displayed in the same window (the normal, default 
setting) they are called standard output. Any window that is used to enter standard 
input and display standard output is referred to as the console. 


Most commands read from standard input, write their output to standard output, and 
write error messages to diagnostic output. By default, standard input refers to text 
that is selected and entered while the tool is running. Standard output and diagnostic 
output appear following the commands. (These input and output defaults can be 
changed using I/O redirection. See Chapter 5 for details.) 


The Enter key 


The Enter key serves as a “do it” button, causing commands to be executed. You can 
type commands in any window and press the Enter key to execute the command line. 
(When no text is selected, the entire line is executed, regardless of where the 
insertion point is on the line.) You can also select command text that is already on 
the screen and press the Enter key to execute the selected text. 


Pressing Command-Return is equivalent to pressing the Enter key. In addition, using 
the mouse to click the status panel in the lower-left comer of the active window is a 
convenient way to get the same result. 


Entering commands 
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Executing several commands at once 


By selecting several lines of command text and then pressing Enter, you can execute 
any number of commands with one stroke. An example is shown in Figure 4-1. 


& File Edit Find Window Mark Directory Build 


CO HD SMPW:Worksheet 


H date -d 
i Tuesday, July 5, 1987 


2 (ACO 0nd Ds (1 a =o od 2) «] ; 
£BGupticate Startup Weeritarey 
(eS 


Figure 4-] 
Pressing Enter to execute selected text 


In Figure 4-1, executing the selected text would first make a new folder (directory) 
named Backup, then copy the files Startup and UserStartup into Backup, and then list 
all of the files in Backup. (Each of these commands, and the pathname syntax, is 
described in the sections that follow.) 


You can also directly execute text files that contain other commands, simply by 
entering the filename of the script. Executing a script has the same effect as selecting 
the commands in an open window and pressing Enter—the only difference is the 
scope of variable and alias definitions (discussed in Chapter 5). 


Important 


Commands that don't produce any output run silently: this facilitates their use 
in scripts. Other commands are equipped with a “run silently” option. 
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Terminating a command 


To terminate a command while it’s executing, press Command-period, the standard 
Macintosh command for this purpose. 


Important 


Many commands (including Asm, C, and Pascal) normally take their input from a 
fille: however, If no file Is specified, they will begin reading from the console (that 
is, from the window where the command was entered: “standard input’). If the 
Shell appears not to be Ilstening to the commands you are entering, it probably 
Isn't: The currently executing command (shown In the active window's status 
panel) may be reading the text that you enter. If a program is reading from 
standard input, you can press Command-Enter (or Command-Shift-Return) to 
indicate end-of-file and terminate Input. (See “Terminating Input With 
Command-Enter” In Chapter 5.) 


The Help command 


The Help command displays summary information for commands. For example, to 
display a description of the Files (ist files) command and its options, type the 
command 

Help Files 


and press the Enter key. You'll see the following syntax description: 


Files [option..] [name..}] > fileList 
-c creator # list only files with this creator 
-d # list only directories 
-f # list full pathnames 
ai # treat all arguments as files 
-l # long format (type, creator, size, dates, etc.) 
~m columns # n column format, where n = columns 
-n # don't print header in long or extended format 
-q # don't quote filenames with special characters 
-r # recursively list subdirectories 
-s # suppress the listing of directories 
-t type # list only files of this type 
-x format # extended format--fields specified by format 


Note: The following characters can specify the format 
Flag attributes 

Logical size, in bytes, of the datafork 
Logical size, in bytes, of the resource fork 
Creator of File ("Fldr" for folders) 

Creation date 

Physical size, in kilobytes, of both forks 
Modification date 

Type 

Owner (only for folders on a file server) 
Group (only for folders on a file server) 
Privileges (only for folders on a file server) 


wmnodranawrnandnoep 


** Note: In Help texts, the square brackets are a syntax element indicating that a 
parameter is optional. An ellipsis (...) indicates that the preceding item may be 
repeated. (Note that this use of the ellipsis is a syntax convention only for Help 
text and documentation; an ellipsis in an actual command line invokes the 
command’s Commando dialog.) Syntax notation is described in the preface to 
this manual. The number sign (#) is the MPW comment character. 


Entering commands 


You can directly edit and execute the text on the screen. For example, assuming that 
your current directory is {MPW}, you can edit the above text as follows: 


1. Use the mouse to select [option...] and [name...]; replace them with the 
option ~1 and the directory name AExamples. 


2. Remove the output specification > fileList. 


The result is a command that will list the files in directory AExamples, in long 
format: 
Files -l1 AExamples 


(AExamples is the directory containing sample assembly-language programs, -l is an 
option that generates “long” output.) Press Enter to execute the command— 
directory information will appear immediately following the command. 


You can also use the Help command to display additional summary information, 
including 


Q an annotated list of all MPW commands 

O an annotated list of the characters that have special meanings to the MPW Shell 
QO descriptions of the syntax of expressions, selections, and text patterns 

O a summary of MPW Shell shortcuts 


For general information about Help, execute the Help command with no 
parameters: 


Help 


This command displays the information shown in Figure 4-2. 


eed H0 :MPW:Warksheet 


& File Edit Find Window Mark Directory Build 


; Help 
mg MPW 2.0 Help Summaries 


Help summaries are available for each of the MPH commands. 
To see the |ist of commands enter "“Halp Commands”. In addition, 
brief descriptions of Expressions, Patterns, Selections, Characters, 
and Shortcuts are Included. 
To see Help summaries, Enter a command such as 
Help commandName § information about commandName 
Help Commands 8a list of commands 7 
Help Expressions S summary of expressions 
Help Patterns ® summary of patterns (regular expressions) 
Help Selections ® summary of selections 
® summary of MPW Shell special characters 
8 summary of MPW Shell shortcuts 


Help Characters 
Help Shortcuts 


ranean ee eas st 


Figure 4-2 
Help summaries 


You can directly execute the Help commands given in the “Help Summaries” list. 


“» Note: The MPW Help file should be in the same directory as the MP W Shell or in 
the System folder. 
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File management commands 


The MPW Shell lets you manipulate files without returning to the Finder. Table 4-1 
introduces the most commonly used file management commands. 


‘» Note: The descriptions in the table omit some of the command options that are 
available. For complete descriptions, see Part II. 


Table 4-1 


Basic file management commands 


Backup [option] -from folder -to folder [/ile...] 


Catenate [ file... ] 


Delete name... 


Directory directory 
Directory 


Duplicate name... targetName 
Exists mame... 


Files [name... ] 


Copy files in source folder to destination folder 
based on modification date. This is useful when 
you maintain an identical backup folder on a 
separate disk. 


Read the data fork of each file and write it to 
standard output. (By default, standard output is 
to the active window, immediately after the 
command.) 


Delete file or directory name. If name is a 
directory, all of its contents are deleted. 


Set the default directory to directory. 


Directory with no parameters writes the 
pathname of the current directory. 


Duplicate file or directory name to file or 
directory targetName. 


Determine the existence of file or directory 
name. 


List names of directories and files. Options allow 
you to include various attributes in the listing. 


GetFileName [options...] [pathname } 


Mount anive... 
Move name... targetName 
New [name... ] 


Newer [option] name... target 


NewFolder name... 
Open [option] {names...] 
Rename namel name2 
Revert 

Save [-a | windows...] 


SetFile [option... ] file... 


Display a standard file dialog box. 

Mount volumes. 

Move file or directory name to targetName. 
Open a new window. 


Compare modification dates between files name 
and target . List files newer than target. 


Create the new directory name. 

Open a window. 

Rename File or Directory namel to name2. 
Revert window to previous saved state. 

Save a window. 

Set file attributes. 


(continued) 
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Table 4-1 (continued) 
Basic fille management commands 


SetDirectory directory Set the default directory. 

SetPrivileges [option] folder... Set access privileges for folders on the file 
server. 

SetVersion [option ...] file Independently maintain the version and 


revision numbers as a resource in the 
application or tool. Optionally, update a 
version and revision string in a source file. 


Target mame Make a window the target window. 
Volumes (name... ] List mounted volumes. 
Which [command | Determine, for the specified command, which 


existing aliases, Shell built-in commands, and 
commands accessed via the Shell variable 
{Commands will be executed when command is 
entered. 


Windows List open windows. 


File and window names 


In the MPW, files and windows are specified in the same way. When a name is passed 
aS a parameter to a command, the system looks first for an open window with that 
name; if no window is found, it looks for a file on the disk. 


The following rules apply to naming: 
OQ Names are not case sensitive. 


Q A single component (file or directory name) of an HFS pathname is limited to 31 
characters. 


© Any character except a colon (:) may be used in a file or directory name. (Colons 
separate elements in a pathname.) 


It’s wisest to avoid using spaces and special characters in filenames. When using 
filenames that contain spaces, you'll need to quote them so that they won’t be 
interpreted as individual words in the command language—for example, you would 
need to specify the name “System Folder” as follows: 


Files "HD:System Folder" 


For the rules concerning quoting, see “Quoting Special Characters” in Chapter 5. 
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Selection specifications 


Commands that take filenames for parameters can also act on the current selection 
in a window. The current selection character, § (Option-6), represents the currently 
selected text in a window. There are two ways to use this character: 


§ Currendy selected text in the target window. (The target window is the 
second window from the front, as explained in Chapter 1.) 


name.§ Currently selected text in window name. 


For example, the Count command counts lines and/or characters in a file. The 
command 


Count -l Sample.a.§ 
counts the lines within the current selection in the window Sample.a. 


The current selection is explained more fully in “Editing With the Command 
Language” in Chapter 5. 


“* Note: The MPW Shell uses a number of special characters (like §) from the 
extended character set. These characters are fully listed in Appendix C. 


Directories and pathnames 


With the hierarchical file system (HFS), specifying a filename alone is often not 
enough to identify a file—you frequently need to specify a pathname. A full 
pathnamie is specified as follows: 


volume :(directory :...] filename 


A full pathname contains at least one colon (:), but cannot begin with a colon. An 
example of a full pathname is 


"HD:MPW:MPW Shell" 


(The quotation marks are required because the filename “MPW Shell” contains a 
space.) 


A partial pathname is usually all you’ll need to specify. When HFS encounters a 
partial pathname, it begins the path at the current default directory. Any name that 
contains no colons or begins with a colon is considered a partial pathname. A 
partial pathname that contains no colons is a leafname. For example, the name 


:AExamples 
is taken as a partial pathname. However, the name 
MPW: 


is taken to be a full pathname (that is, a volume name only), rather than meaning the 
directory HD:MPW. (When in doubt, you can always specify the full pathname for a 
file or command.) 


Double colons (::) in a pathname specify the current directory’s parent directory; 
triple colons specify the “grandparent” directory (two levels up), and so on. See the 
File Manager chapter in Volume IV of /nside Macintosh for more information on 
HFS conventions. 


«* Note: Notice that there’s no single “root” directory—each volume name (that is, 
disk name) is a separate starting point for a directory tree. 


File and window names 


Figure 4-3 is a directory tree showing the arrangement of MPW files and folders. 


System Folder: MPW: 


MPW Shell Startup UserStartup AExamples: Libraries: Tools: 


Instructions.a MakeFile.a Sample.a 


Runtime.o ToolLibs.o 


Link Print Rez Search 


Figure 4-3 
Hierarchical directory structure 
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You can use the Files command to list the names of files and directories. For 
example, the command 


Files HD:MPW: 
might display the following: 


:AExamples: 
:AIncludes: 
:Applications: 
: Libraries: 
:RIncludes: 
:Tools: 
'MPW Shell' 
MPW.Help 
Quit 

Resume 
Startup 
Suspend 
SysErrs.Err 
UserStartup 
Worksheet 
etc. 


In the output of the Files command, the names that begin and end with colons are 
directory names, and the other names are filenames. All of these names are partial 
pathnames—in this case, “HD:MPW” forms the beginning of each pathname. Also 
note that filenames containing special characters are quoted. 


Command search path 


When you enter a command name (that is, a leafname), the Shell searches for the 
command in the directories listed in the Shell variable {Commands}. As described 
in Chapter 5, this search path is initially set to 


:(the current directory) 
HD:MPW:Tools:, 
HD:MPW:Applications:, 
HD:MPW:Scripts: 


This means that when you type any command the Shell first assumes that you want to 
execute a tool, if it can’t find the tool, it then assumes that you want an application, if 
it can’t find the application, it then assumes that you want a command script. If your 
frequency of use is different, you can change the search path to improve the Shell’s 
performance. (See Chapter 5.) 


File and window names 


Changing directories 


You can change the default directory with the Directory command. Assuming you 
have a hard disk named HD, you could change the default directory to the directory 
AExamples in the MPW folder with the command 


Directory HD:MPW:AExamples 


Like most commands, Directory runs silently—it generates output only if an error 
occurs. To verify that you have set the appropriate directory, enter the Directory 
command with no parameters: 


Directory 
This command displays the default directory. 


Remember that to specify a pathname containing spaces or other special characters, 
you'll need to quote it by surrounding it with single or double quotes. (See 
Chapter 5.) 


An aside: the Alias command 


For frequently used commands such as Directory, you may get tired of typing the 
entire command name. You can easily define your own alternate names with the 
Alias command. For example, 


Alias dir Directory 


After executing this command, you can execute the Directory command by entering 
the new command name: 


dir 


To make an alias definition part of the Shell’s standard startup procedure, place the 
definition in the file UserStartup. See Chapter 5, “The Startup and UserStartup Files.” 


Pathname variables 


One way of specifying a pathname is by using Shell variables. For example, the Shell 
variable {MPW}, defined in the Startup file, expands to form the full pathname for 
the MPW folder, in this case “HD:MPW:” (assuming that the MPW folder is at the top 
level). Thus, the previous Directory command could be entered as 


Directory "(MPW}AExamples" 


In this particular case, the quotes aren’t necessary. If you adopt the practice of never 
using spaces or other special characters in a pathname, then you don’t need to 
bother with quotes. On the other hand, if a pathname may contain spaces or other 
special characters, then it would be a good idea to use quotes whenever variables are 
included in a pathname. 


You can use the Set command to define and redefine variables, as described in 
Chapter 5. To see the values of all currently defined variables, enter the Set 
command with no parameters: 


Set 
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Wildcards (filename generation) 


You can specify a number of files at once by using the wildcard characters ? and = 
(Option-X). The ? character matches any single character (except a colon or 
Return); = matches any string of zero or more characters (other than colon or 
Return). For example, the command 


Files =.a 


lists all filenames in the current directory that end with the suffix “.a”. (Several other 
wildcard characters can also be used to generate filenames—see “Filename 
Generation” in Chapter 5.) 


Commando dialogs 


The Commando user interface lets you operate any properly configured MPW 
command by means of a special Macintosh dialog, rather than the traditional 
command line interface. Commando dialogs may consist of several dialog boxes 
containing a variety of controls. You can choose options, select filenames, pick 
directories, and read help information for each option. Commando lets you operate 
MPW commands in a more intuitive format. All options are visible, and help text for 
each option can be instantly displayed in the frontmost dialog box. 


Because of the complexity of many MPW commands, several specialized controls 
and nested dialog boxes have been implemented for them. The various types of 
controls and dialog boxes are introduced below. Other unique dialog boxes, specific 
to a particular command, are described with the command in Part II. 


Invoking Commando dialogs 


To invoke a Commando dialog for tools and other commands from the worksheet: 
type the command name followed by either an ellipsis (...) or the word Commando in 
front of the command line. 


** Note: To get the ellipsis character,hold down the Option key while 
simultaneously typing the semicolon (;) character. Although three periods 
closely resemble an ellipsis character, Commando won't be fooled; you must 
use Option-semicolon to get the true ellipsis character that invokes Commando. 


The ellipsis may appear anywhere in a command line (except with quotes or after d) 
and it is considered a word-break character. The ellipsis invokes the Commando user 
interface after the Shell has carried out all alias and variable substitutions. The entire 
command line is passed to Commando and the output of Commando is then 
executed by the Shell. 


Alternatively, if you don’t want the resulting command line to be immediately 
executed, you can type 


commando toolname 


In this case, Commando will not find a command if the command has been aliased 
to a different name. The tool’s frontmost Commando dialog box is displayed. 
Clicking the Do It button writes the command line to standard output (that is, the 
window in which you typed the command) instead of executing it immediately. This 
second method of using dialog boxes is useful for building command lines that are to 
be cut and pasted into scripts. 


Commando dialogs 


Using Commando dialogs 


The function and appearance of Commando dialog boxes may vary widely 
according to.the syntax and semantics of the particular command or tool selected. 
The basic dialog box is typical of a simple command such as Date, the first example 
used above. Type 


Date ... 


Be sure to use Option-semicolon to get the ellipsis. Then press Enter. Figure 4-4 
shows the resulting Commando dialog box for Date. 


Date Options 


;- Date/Time Amount of Detail 
© Both date and time | © Full date 
i © Date only | |O Abbreviated date | 
O Time only | | O Short date | 
Output Error 


Command Line 

[ps | 
Help 

a the current date and time. | 


Figure 4-4 
Date dialog box 


Most dialog boxes share the basic structure shown in Figure 4-4. Various controls for 
options and parameters appear in the largest, upper area of the box. Date has two 
parameters, “Date/Time” and “Amount of Detail.” Each of these parameters is 
defined by a radio button control. The default settings for Date appear preselected as 
the topmost radio button for each parameter. 


Clicking and holding down the mouse button on any control or option displays help 
information in the standard help window at the bottom of every Commando dialog 
box. 


Use the output box to redirect output. See the section “Redirecting Output” later in 
this chapter. 


The Command Line window displays the command line resulting from the options 
you select from the dialog box. As you select options or change parameters, this 
Command Line box is continuously updated. 


Clicking the lower-right Do It button passes the completed command line back to the 
Shell for execution. Alternatively you can press the Enter key. If you change your 
mind, you can click the Cancel button, which is the same as pressing 
Command-period. 
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Standard dialog box controls 


This section describes the most frequently encountered Commando dialog box 
controls. 


Generic text parameters 


Not only do tools have options, they also have parameters. Nonspecific parameters, 
where the parameter can be just about any string, are simply entered in a editable text 
field. For items where text is required, the text is quoted by Commando before being 
passed to the Shell. You can scroll the line right and left (by dragging) if the text in 
the box is longer than the text box. Here’s an example of an editable text field: 


Mark the selection with what name? 


ee) 


Repeatable options 


Various text field options, such as the -dfefine] option in Rez and Asm, may be 
specified more than once. The control below shows an option of this type. The 
number of lines displayed is controllable by the tool’s builder. The small window is 
basically an area where text can be entered, very much like the Notepad desk 
accessory. This window does not automatically wrap around lines larger than the 
window area. Instead, it scrolls left and right. You create a new line by pressing the 
Return key. Scroll the window horizontally by dragging. The window is scrolled 
vertically either by dragging or by the scroll bar control. 


Preprocessor defines: 
Language=english 
size=height*200 


Radio buttons 


Ce) ae 


Some options are mutually exclusive and are therefore available as a set of radio 
buttons. The default setting of the button corresponds to the default state of the 
option. Groups of mutually exclusive items are often surrounded with a labeled 
perimeter: 


Print Quality 
O High 

@ Standard 
O Draft 
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Check boxes 


An option, such as the Assembler’s -print option, may have many simultaneous 
settings. Options like this are implemented with check boxes (versus on/off radio 
buttons). Most of the MPW tool’s options are Boolean flags. Check boxes are used 
for these types of options also and are usually surrounded by a labeled perimeter. 


Listing Control 
&) Show macro expansions 
{kj Allow automatic page ejects 
] Show warning messages 

{ Show macro call statements 
{] Show generated object code 
CJ Show up to 255 bytes of data 
{) Show macro directive lines 
{] Show header lines 

{) Show generated literals 

(J Show assembly status 


Shadow pop-up menus 


Some options require the name of a window, alias, font, or Shell variable. 
Commando will display a field of this type with a shadow: 


Window | HD:0S:Worksheet 


When you click inside the shadowed box, a pop-up menu displays all the choices for 
that particular field (that is, windows, aliases, fonts, or Shell variables). The menu 
box is aligned around the current selection. Also, the current selection is checked in 
the menu box. As long as the mouse button is held down, the menu behaves like the 
standard pull-down menu. If necessary, the pop-up menu will scroll. When the 
mouse is released within a menu item, that item then appears in the shadowed box. 


Window |“HD:0S:Worksheet 
HO:MPW:MyCroft:test.c 
HO:MPW:MyCroft:getopt.c 


Other pop-up variations 


Some options are similar to the pop-up menus above but also allow a little more 
flexibility. The Menu Name box in AddMenu allows you to type in the name of a new 
menu or select an existing menu name from a list of names. 


4-16 Chapter 4: Using MPW: The Basics 


Click on the menu icon at the right of the box to display a pop-up menu containing 
the existing choices. 


Menu Name 


Find 
{Windows 
Mark 
Directory 
Build 


Drag down the pop-up menu until the item you want is highlighted and then release 
the mouse button. The selected item will appear in the text-edit box. 


Multiple input files 


When a tool can handle multiple input files of the same type (C, ASM, Rez, and so 
on), only a single button is displayed. 


Source Files 


Clicking on the button displays a modified standard file dialog box. Commando 
adds some functionality to the standard file package (SFGetFile) to let you select 
multiple files in different directories. Another scrollable list appears under the file 
list. Use the standard file controls to select files. After you’ve selected a file with the 
Add button, the dialog box does not go away. Instead, the file is added to the lower 
list. You can delete a file from the list by selecting it Gin the lower list) and clicking 
Remove. When all desired files have been selected, click Done or Cancel to return to 
Commando’s dialog box. 


A tool may tell Commando that the tool requires files with a particular extension. A 
radio button lets you display and select any text file (or whatever type the tool wants). 
When you select a folder, the Open button reads “Open.” When a file is selected, 
this same button is labeled “Add.” If you select a file that has already been added to 
the lower list, then the file in the lower list is selected (and scrolled into view if 
necessary), and the Remove button undimmed. 


© CExamoples 
QO Count.c 
O Memory.c 
QO Sample.c 


eee Cmive} 
QO testperf.c 


Done 


Cancel 


@ Files anding In .c © All text fies 
Source: 
>CEnampiles:Memory.c 
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Multiple directories 


Some tocls, such as C and Asm, have options that let you specify directories to 
search when looking for various files. Clicking a single button, like this one, will 
display a modified standard file dialog box: 


include Directories 


The selection of multiple directories works the same way as the selection of multiple 
files. In this example, however, only folders are visible. Because a selected directory 
has the potential for being both opened and added to the lower list, there must be 
two controls for both operations. Clicking the Add button adds the directory selected 
in the upper list to the lower list. The Open button operates in its normal manner: 
Clicking it opens the selected folder. You can delete a directory from the lower list by 
selecting it Cin the lower list) and clicking Remove. Finally, clicking Continue or 
Cancel returns control to Commando. 


fAidd Current Directory: 


© AEHXamoples 
© Alncludes 
© Applications 
(1 CExamples 
© Cincludes 
© CLibraries 
© Commando 
© Debuggers 
© Libraries 


Include Search Paths: / 
:<CExamples: 


Multiple files and/or directories 


For MPW tools or built-in commands that can deal with both multiple files and 
directories, this dialog box, almost the same as the one shown above, lets you select 
files and directories. The model is almost the same as the one above, except that 
both files and folders are visible. Selecting anything in the upper scroll window 
highlights the lower Add button. The controls work as shown in the example above. 
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Single input or output file 


You select options or parameters that require a single file @whether it be for input or 
output with a control similar to the example below. Clicking in the dotted rectangle 
displays a pop-up menu with choices depending upon the tool. The first choice can 
be either Default Output or No Output (or, if the file is an input file, Default Input or 
No Input). The Default Output is used for tools that write to a default output file if one 
is not specified. Link and Rez, for example, write to link.out and rez.out if no explicit 
output file is specified. If Input File... or Output File... is selected, SFGetFile (for 
input files) or SFPutFile (for output files) is displayed so that a file can be chosen. If 
the filename selected is too long to fit in the space provided, the middle of the path is 
annotated with “...”. 


Resource Output File[rez.out | 


Here’s an example of an output file pop-up menu: 


/ lttite auigul te Kez.autl 


Select an existing output file... 
Write output to a new file... 


Output file where a file or directory may be specified 


The various compilers have options to specify the object filename or the object file 
directory. Commando displays a pop-up menu similar to the one above, except that 
the standard dialog box that appears when you select the Output File or Directory... 
item looks like the one below. When you select a directory in the file’s window, the 
File button changes to Directory. The File button is dimmed when the text-edit field 
is empty. 


File/Directory R29 SILT LLL Me ALL 


Specify object file name or select directory. 


This dialog box appears when the Output File or Directory... item is selected: 


Select Current Directory: 
& AExamples 
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New directories 


The NewFolder command lets vou snecify the creation of multinle directories. The 

example below (based upon SFPutFile) is used to create multiple directories. When 

you type a directory name in the middle text-edit area and click the Add button (Cor 

press Return), a pathname is added to the lower list. The root of the new directory is 
the same as what is displayed in the upper scroll list. You can continue to add more 

directories. Click the Done button to close the dialog box. 


Q Caunt.a 

Q Caunt.r 

D (nstructians 
QD Makefile 

2 Memary.a 
A Sample 


Special dialog box controls 


Commando uses standard Macintosh text-edit boxes, radio buttons, and check 
boxes. In addition to these, you’ll encounter some specialized controls, because of 
the variety of options and parameters and certain dependencies between them. 
These various types of specialized controls are introduced below. 


Nested dialog boxes 


Some tools, such as Rez and PasMat, have more options and parameters than can fit 
into one dialog box. The additional options are grouped into nested dialog boxes 
that are available from the first dialog box. Figure 4-5 below shows, as an example, 
the first dialog box of Rez. 


Rez Options 

Resource Output File——_————____-..._--. [ Redeclared types ok 
Type | C Progress information 
| Creator |7777? | 
| -@ Rewrite resource file Description Files... 
CJ Make resource file read-only #Include Paths... 
j fecaa Alignment ———_—----—., | ae 
| @© Byte OWord OLongWord | 
: ources inte resource le 


© Merge resources into resource file 
Redirection... 


Command Line 
fe | 


Help 


Rez ts a tool used to compile resources. 


DOK ta replace protected resoures 


Figure 4-5 
Rez: the first dialog box 
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Note the five control buttons at the right side of the “Rez Options/Parameters” 
window. When you click one of these buttons, a nested dialog box appears with the 
title of the selected button. For example, selecting the button labeled 
“Preprocessor...” displays the nested dialog box shown in Figure 4-6. 


Preprocessor... 
Defines: Undefines: 


Ld 


Command Line 
& | 
Preprocessor variables can be DEF INE'd and UNDEF INE‘d in this dialog. - ——— 
|_Continue _| 


Figure 4-6 
Rez: nested Preprocessor dialog box 


As you type in the preprocessor defines and undefines, the command line you began 
in the first dialog box is further updated in the Command Line window of the nested 
dialog box. The lower-right Do It button in a nested dialog is always labeled 
“Continue.” Clicking Continue closes the nested dialog box, and again displays the 
first dialog box with the command line updated to show the options and parameters 
selected in the nested dialog box. If you click Cancel, changes from nested dialog 
boxes are not recorded and you return to the first dialog box. From there you can 
then select another nested dialog box. 


Redirecting output 


Every tool that can write information to standard output or to standard error has 
controls to assign destinations for this output. Consider the Error Output window in 
the Redirection nested dialog box of Rez, shown in Figure 4-7. 


Redirection... 
input 


Command Line 
fed | 


Rez can read standard input and send warnings to diagnostic output. 


[Continue | 


toe 
Click this button to open a dialog with the redirection controls. Cancel 


Figure 4-7 
Rez: nested Redirection dialog box 
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Clicking inside the Error window displays the pop-up menu shown below. 


Error 
SNe Guipul Redirection 
New File... 

Existing File... 
Window... 

Current Selection in Window... 
Current Selection in Target Window 
Standard Output 
Standard Diagnostic 


Null Device 
Console 


Here “Null Device” has been selected. When the mouse is released, the filename 
dev:null appears in the Error window. Whenever you select an output redirection, 
the two radio buttons directly beneath the Error window are activated. 


Selecting Existing File in the pop-up menu displays the standard file dialog box. 
Selecting New File brings up the standard output file dialog box and lets you create a 
new file. Selecting Window brings up a list of the windows to choose from. Because a 
window is a file, a window could also be chosen with the Existing File command. 
When you select Current Selection in Target Window, output is redirected to §. 
Selecting Current Selection in Window also brings up a list of windows to choose 
from. When you choose a window, output is redirected to window.§. When you 
choose any file other than a new file, the Overwrite and Append buttons are 
activated. These buttons correspond to the functions of the >,2 and >>, 22 
redirection operators, respectively. Selecting No Output Redirection clears the 
dimmed box so that no redirection occurs. 


After you release the mouse over Null Device, the command window looks like this: 


Error @2 02 


The Diagnostic Output windows and Standard Input windows (in the case of tools that 
read standard input) work in a similar fashion. 


Options dependent on other options 


Some options may be dependent on another option. For example, the -hf (header 
font) and -hs (header size) options of the print tool don’t mean anything unless the 
-h (header) option is specified. Commando implements this model by disabling all 
controls dependent upon some other control. When you check (or otherwise 
activate) the main control, the dependent controls are enabled. Another example is 
the AddMenu ‘command. The syntax of this command is 


AddMenu [{menuName [itemName [command...] } ] 
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An itemName cannot be entered until a menuName is entered. Likewise, a command 
cannot be entered until an itemName is entered. 


Cammands 


Here is the same set of options after “Find” has been typedin the first text-edit entry 
field. Notice that as soon as something is entered in the field, the “Item Name” entry 
is enabled, but the Commands field remains dimmed. 


MenuName[Fing 
Cammands 


When an item is selected for the Item text-edit box, the Commands field is enabled. 


Commands 


There may be several text-edit boxes that are disabled (dimmed) until you have 
entered something in the adjacent enabled text-edit box. 


Three-state controls 


Some options, like the -a option of Setfile, need the support of a three-state control. 
For example, Setfile can set, clear, or do nothing to the bundle bit. Clicking this 
control cycles through its three states. The color of the diamond determines its state: 


Gray—Don’t touch the flag 
White—Clear the flag 
Black—Set the flag 


Attributes 


©} Locked 
} Invisible 
@ Bundle 

@ System 

@ Protected 
@ Open 

@ Changed 
@ Inited 

} on Desktop 
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Chapter 5 


Using the 
Command 
Language 


5-1 


So far, we’ve introduced only isolated groups of commands without treating the 
Shell’s command language as a whole. This chapter describes the complete syntax of 
the MPW command language and explains its use. Each command is defined in 
detail in Part II. 


Overview 


The command language provides the following features: 
O built-in and user-definable variables of the form {variableName 
© command aliases, used to create alternate names for commands 


O command substitution, by which commands enclosed in back quotes (~...~ ) are 
replaced by their output 


QO a quoting mechanism for disabling special characters or inserting invisible 
characters in text: d literalizes a single character; '...' and "..." quote strings 


O an extensive set of structured commands for controlling the order of command 
execution, including Begin...End, If...Else...End, and For...In...End 


O filename generation with “wildcard” operators such as = and ? 

O redirection of input and output with the <, >, >>, 2, and 22 operators 

When you enter command text, the Shell first interprets and processes all special 
symbols, before actually running the command. The order of interpretation is 
explained later in this chapter under “How Commands Are Interpreted.” For the 


most part, the order of presentation in this chapter follows the order of 
interpretation by the Shell. 


In order to begin using MPW, you should read the following sections of this chapter 
as a minimum: 


O the opening sections of the chapter, which describe the basic form of all 
commands: “Types of Commands,” “Entering and Executing Commands,” and 
“Structure of a Command” 


O “Command Scripts” and “Special Scripts” 
O “Variables” 


O “Quoting Special Characters” 


The operators and syntax of the command language are summarized in Appendix D. 


Types of commands 
In all, four kinds of commands are provided: 
= Built-in commands, such as Files or Duplicate, are part of the MPW Shell. 


= Command scripts, such as Startup, are text files that contain commands. You 
can combine any series of MPW commands in a text file, and execute the file by 
entering its filename, just like any other command. You can also pass parameters 
to a script and use them in commands within the file. 


m Tools, such as Link or Asm, are executable programs (that is, separate files on the 
disk) that are fully integrated with the Shell environment. 


= Applications, such as ResEdit or MacPaint®, are stand-alone programs that can 
be launched from the Shell, but run outside the Shell environment. 


5-2 Chapter 5: Using the Command Language 


To execute a tool, application, or script, you need to have the proper program file 
on your disk. 


“* Note: A built-in command overrides a script or executable program with the 
same name. You should therefore use either full pathnames or quotes to specify a 
command file or program with the same name as a built-in command. (Quotes 
work for this purpose because the names of built-in commands must appear 
unquoted—see “Quoting Special Characters” later in this chapter.) 


“e Note. The Shell will not execute tools whose modification date is 12:00 AM 
1/1/04. 


Entering and executing commands 


Press the Enter key to execute command text. You can select command text on the 
screen and press Enter to execute the selected text. If no text is selected, pressing 
Enter executes the entire line that contains the insertion point. Alternatively, you can 
use the mouse to click the Status Panel in the worksheet’s lower-left corner, or press 
Command-Retum; both of these have the exact same result as pressing the Enter key. 


Important 


lf no text is selected, pressing Enter always passes the entire line to the Shell (or 
to whatever other program happens to be reading from the console—this rule 
also applies to your own integrated programs that run within the Shell). 


Caution 
lf you enter a line that ends with the Shell escape character, 0, the command 
interpreter will pause, waiting for the rest of the line. 


All commands return a status value: 0 indicates successful completion; nonzero 
values usually indicate an error. This value is returned in the {Status} variable, 
described later in this chapter. 


Negative status 


The command interpreter will return negative status values when it encounters an 
error. These values are as follows: 


-1 Command not found, script is a directory, script is not executable, or script 
has a bad date. 


-2 Filename expansion failed or there was an error in the expression syntax. 


-3 Bad syntax. Quotes and braces were not balanced, or were missing end or “)” 
command. Error in control constructs. 


-4 _— Missing filename following I/O redirection or the file could not be opened. 


-5 Invalid expression (If, Break If, Continue If,and other such constructs). 


Entering and executing commands 


-6 Tool could not be started. 

-7 Runtime error during tool execution. Most likely an out-of-memory error. 
-8 — User aborted the tool from the debugger. 

-9 User aborted the tool with Command-Period. 


These values can be used to distinguish between errors returned by the commands 
themselves and errors returned by the Shell. 


Important 


All negative numbers are reserved for the Shell. Use only positive numbers for 
errors in tools or scripts. 


Structure of a command 


A command is written as a list of words separated by blanks. (Blanks may be either 
space or tab characters.) The first word is the name of the command, and each word 
that follows is passed as a parameter to the command. The general form of a simple 
command is 


commandName_ [ parameters...) commandTerminator 


Each of these elements is described below. 


Command name 


The command name is either the name of a built-in command or the filename of 
the program or script to execute. Command names are not case sensitive. Alternate 
names can be defined for a command—see “Command Aliases” in this chapter for 
information. 


The command name is passed to tools and scripts as parameter 0, and can be 
referenced by scripts in the variable {0}, explained later in this chapter under 
“Variables.” 


Parameters 


Each of the subsequent words in a command is a parameter to the command or to 
the command interpreter. Note that certain parameters, such as I/O redirection, are 
interpreted by the Shell, and never seen by the command itself. Variables are also 
interpreted before being passed to the program. 


By convention, there are two distinct types of parameters to commands: options 
and files. See the “Command Prototype” section at the beginning of Part II for more 
details on these conventions. 


You can reference parameters within scripts by using the variables {1}, {2},...{7}. 
(See Table 5-4.) 
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Command terminators 


Each command is normally terminated by a return character. Commands can also 
be terminated by the pipe symbol (1), the conditional execution operators (&& and 
| 1}, or the simple command terminator (;). Each of these symbols may be followed 
by a return. Table 5-1 describes the command terminators in order of decreasing 
precedence. 


Except as modified by structured commands, commands are read sequentially and 
executed as they are read. 


Table 5-1 
Command terminators 


cmd1 | cmd2 Saves the standard output of cmd1 in a temporary file and uses 
it as the standard input of cmd2. (Standard I/O is explained 
later in this chapter.) 


Note: In MPW, unlike UNIX systems, the commands execute 


sequentially. 

cmdal && cmd2 Executes cmd2 only if cmd1 succeeds (that is, returns a status 
value of 0). 

cmd1 || cmd2 Executes cmd2 only if cmd] fails (returns a nonzero status 
value). 

cmdl1 3; cmd2 Executes cmd1 followed by cmad2; this terminator allows more 


than one command to appear on a single line. 


These command terminators may be applied to both simple and structured 
commands. They all group from left to right. Parentheses can be used to group 
commands for conditional execution and pipe specifications. Some examples 
follow. 


Files | Count -l 


This command pipes the output of the Files command (a list of files and directories) 
to the Count command, which counts the lines in the list. 


Asm Sample.a && Link Sample.a.o -o Sample.code || 
(Echo Failed; Beep) 


This example begins by assembling Sample.a. If that operation succeeds, it links the 
object file; but if the assemble-and-link operation fails, it echoes the message 
“Failed,” and beeps. 


Command continuation 


You can continue a command onto the next line by typing d (Option-D) followed by 
a return. Both characters are discarded when the line is interpreted. The return must 
come immediately after the 0, with no blanks or comments between them. (For 
more information about the d escape character, see “Quoting Special Characters” in 
this chapter.) 


Echo This is all @ 
one command 


Notice that the output appears on one line. 


Structure of a command 
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Comments 


The number sign (#) indicates a comment. Everything from the # to the end of the 
line is ignored. (Comments always end at the next return, even if the return is 
preceded by a d.) 


Echo This is echoed. # This is not. 
Echo parameters # comment @ 
more parameters # another comment 


Simple versus structured commands 


All of the commands introduced so far have been simple commands. Simple 
commands consist of a single keyword, followed by zero or more parameters. Simple 
commands are distinguished from structured commands—commands such as 
For and If, which let you control the order in which other commands are executed. 
For example, 


For file In =.c; Count {file}; End 


All of the structured commands are built-in, and usually have more than one 
keyword. The entire structured command is read before its execution begins. 


Also see “Structured Commands” in this chapter. 


Running an application outside the Shell environment 


You can run an application outside the MPW Shell environment by executing the 
program name just like any other command. For example, 


ResEdit 


The application is loaded and launched as if it had been started from the Finder. Any 
files specified as parameters are passed to the program via the application parameter 
handle, in Finder fashion. (See “Finder Information” in the Segment Loader chapter 
of Inside Macintosh.) The following option is available on the command line: 


-p file... Tell the program to print the specified files. 
For example, 
MacPaint -p "HD:Screen 1" "HD:Screen 2" 


This command tells the Shell to run MacPaint (assuming MacPaint is in adirectory 
listed in the Shell variable {Commands}, and to print the files Screen 1 and Screen 2. 


The Shell environment is saved when the application is launched and restored when 
the application terminates. (These actions are performed by the Suspend and 
Resume command files, described below.) 


Caution 


Running an application from a command script terminates tne script. 
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Command scripts 


You can create your own commands by writing text files of previously defined 
commands, called scripts or command files. You can execute such a file just like 
any other command within the Shell environment—the name of the file you created 
is the name of the new command. 


For example, 


Date 

ECHO VOLUMEC'S oi oidcevere agora wd Sed Bue ale oie ew we Gaia a OS Oe eS eS 
Volumes 

Echo “Current: DI TE@GEORY 6 essereceye:dceyeelaie fers, eee oles ow alsiaca ee ates 
Directory 

ECHO PL LOS ace coe sticneiera lo 1o/ site gyrelis eile leone ietiet bre Sie te %er's ee eccaleile alee. a: 6 Gliese 
Files 


If this text is on the screen, you can execute it by selecting it and pressing Enter. You 
could also save this text as a script so that it’s always available. To save it under the 
name “Info”, for example, you could first select the command text, and type the 
following command in another window: 


Duplicate -d § Info 


You can now execute this series of commands by entering the command name Info. 
(Recall that the § character indicates the selection in the target window.) 


You can pass parameters to a script just as you would to a predefined command, 
using the normal Shell syntax: 


filename ([ parameters... | 


Parameters can be referred to within the scripts by using the built-in variables {1}, 
{2},...{}, explained below under “Parameters to Scripts.” 


‘* Note: As a matter of convenience, scripts (as well as applications and tools) are 
usually kept in directories that the Shell automatically searches when a leaf name 
is given for a command name. This convention allows you to invoke the 
command by using its leaf name instead of its full pathname. The Shell variable 
{Commands} contains a comma-separated list of directories to be searched; you 
can easily modify it to include additional directories. 


Special scripts 


The scripts described in this section are provided with MPW. You can modify 
commands in each of these files to suit your needs. 


Important 


Each of these scripts must be in the same directory as the MPW Shell, or in the 
System Folder. 


Special scripts 
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The Startup and UserStartup files 


When you start up the Shell, commands are initially read from a file named Startup. 
The Shell executes the commands in Startup as if you had entered them interactively. 
The Startup file provided with MPW contains several default variable and alias 
definitions. You can modify the commands in Startup to suit your own needs; for 
instance, you can change the default pathnames to suit a special directory 
configuration. 


Startup executes another script called UserStartup. It’s recommended that you use 
this file for your own changes and additions to the startup sequence. You can 

redefine the variables defined in Startup, set and export any number of additional 
command-language variables, and define aliases and create menu items. Aliases and 
variables are fully described in the sections that follow. 


Suspend, Resume, and Quit 


When you run an application from the Shell, commands are read from the file 
Suspend. When you quit the application and return to the Shell, commands are read 
from the file Resume. The Suspend and Resume files save state information about 
variable definitions, exports, aliases, and windows before ninning an application, 
and restore the state after returning to the Shell. 


When you quit from the Shell, commands are read from the file Quit. The Shell 
executes these commands before closing any windows. 


“» Note: If you cancel from the Quit command, the Quit file will already have been 
executed. 


Like Startup and UserStartup, these scripts run as if you had entered the commands 
interactively. You can modify them to suit any special requirements you might have. 


Command aliases 


An alias is an alternate name for a command (and possibly some parameters). The 
Alias command is used to define aliases, and to display the list of aliases. If an alias 
has been defined, it will be recognized by the command interpreter and the 
corresponding definition will be substituted. 


“* Note: Variable substitution and alias substitution occur on the alias definition 
itself, after it has been substituted. 


The following commands are used to define and undefine aliases: 


Alias name word... Name becomes an alias for the list of words. 

Alias name Displays any alias definition associated with name. 
Alias Displays all alias definitions. 

Unalias name Removes any alias definition associated with name. 
Unalias Removes all alias definitions. 


Aliases are local to the script in which they are defined (and are globally available if 
they are defined in the Startup file or entered interactively). Aliases are automatically 
inherited from enclosing scripts, and may be redefined locally. However, aliases 
redefirted locally will revert to their previous value when the script terminates. 


See the Alias and Unalias commands in Part II for a complete specification of aliases 
and several examples. 
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Executable error messages 
The following alias is defined in the Startup file: 
Alias File Target 


That is, the word “File” is defined as an alias for the Target command, which opens a 
file as the target window. (See Chapter 6.) This alias is useful when a compiler returns 
an error message such as 


### Not a parameter name: counts 
File "Count.c" ; line 73 


By placing the insertion point anywhere on the line or by selecting the entire line and 
pressing the Enter key, you'll automatically open the specified file as the target 
window, find and select the offending line, and bring the window to the top. The 
command that the Shell actually executes is 


Target "Count.c" ; Line 73 


“Line” is a script, which automatically finds and selects a line by number and then 
brings the target window to the top. 


Variables 


The Shell provides several predefined variables and allows you to declare any 
number of additional variables. Variables are used for 


QO shorthand notation 

G providing status information 

O local variables in scripts 

Q parameters to scripts and tools 

Q setting certain defaults for the MPW Shell 


You can define or redefine variables with the Set command, and remove variable 
definitions with the Unset command. For example, 


Set PFiles HD:MPW:PFiles: 
This command defines a variable {PFiles} with the value “HD:MPW:PFiles:”. 


Variables have strings as their values. You can reference them by using the notation 
{name}, where name is the name of the variable. When a command containing a 
variable (2ame} is executed, {mame} is replaced with the current value of the 
variable. For example, 


Files {PFiles}Src.p 


In this example, {PFiles} is replaced with its definition before the command is 
executed. 


A variable may form one or more words, or part of a word. If a variable is undefined, 
{name} is removed (that is, replaced with the null string). 


Variable names are case insensitive, and can’t include the right brace character (}), 
for obvious reasons. It’s wise to avoid using any special characters in variable 
names—future extensions to the command language may assign special meanings to 
some of these characters. 


Variables 
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“» Note: For variables such as {Exit} and {CaseSensitive} that can be either “true” or 
“false,” the variable is considered “true” if it is set to anything other than zero or 
the null string (a string of length zero). The variable is considered “false” if it is 
set to zero, null, or undefined. The best way to set one of these variables is as 


follows: 


Set Exit 1 
Set Exit 0 


# turn {exit} on 
# turn {exit} off 


(These values also apply to expressions that return a Boolean value, defined later 
in this chapter under “Structured Commands.”) 


Predefined variables 


Table 5-2 lists the variables defined by the MPW Shell. These variables provide the 
status value returned by the last command, and the pathnames of several files and 


directories. 


Table 5-2 


Variables defined by the Shell 


{Active} 
{Aliases} 


{Boot} 


{Command} 


{ShellDirectory} 
{Status} 


{SystemFolder} 


{Target} 


{Windows} 


{Worksheet} 


Full pathname of the current active window. 


Contains a list of all defined aliases with each name separated by 
a comma. The list contains only the names, not the definitions. 
Commando uses this variable with the built-in commands Alias 
and Unalias. Commando needs this variable in order to know 
the names of existing variables. {Aliases} must be exported. 


Volume name of the boot disk. 


Full pathname of the last command executed. (For built-in 
commands, this is the name of the command.) 


Full pathname of the directory that contains the MPW Shell. 


Result of the last command executed. (A value of 0 means 
successful completion. Any other value is an error code: 
Typically, 1 means an error in parameters, and 2 means that the 
command failed.) 


Full pathname of the directory that contains the System and 
Finder files. 


Full pathname of the target window (that is, the second window 
from the top—by default, this is the window where editing 
commands take effect). 


This variable contains a list of the current windows with each 
name separated by a comma. Commando uses this list to allow 
redirection of output or input to or from existing windows. 
Commando needs this variable in order to know the names of 
the current windows. {Windows} must be exported. 


Full pathname of the Worksheet window. 
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Variables defined in the Startup file 


Table 5-3 lists the variables that are defined in the Startup file (described in the 
“Special Scripts” section in this chapter). These variables define pathnames and 
default settings to the Shell, and are referenced by the Shell and by some of the MPW 
tools. You can change any of these definitions to suit your own needs. 


** Note: Hierarchical file system (HFS) pathname conventions are described in 


Chapter 4. 
Table 5-3 


Variables defined In the Startup file 


Variables referenced by the command Interpreter 


{MP W} 


{Commands} 


The volume or folder containing the Macintosh Programmer’s 
Workshop. Initially set to " {Boot }MPW:". If your MPW 
directory is somewhere other than the root of the boot volume, 
modify the value of {MP} in the Startup file. 


A list of the directories that the Shell searches when looking for a 
command to execute. Directories in the list are separated by 
commas. A single colon indicates the default directory. 
{Commands} is initially set to 


:, (MPW}Tools:, (MPW}Scripts:, (MPW}Applications: 


—that is, the current directory, then HD:MPW:Tools, then 
HD:MPW:Scripts, and then HD:MPW:Applications. 


Variables referenced by the command interpreter 


{Exit} 


{Echo} 


{Test} 


{Commando} 


When {Exit} is set to a nonzero value, scripts terminate whenever 
a command returns a nonzero status. This nonzero status is 
returned as the status value of the script. (See the {Status} variable 
in Table 5-2.) {Exit} is initially set to 1. 


When {Echo} is set to a nonzero value, commands are written to 
diagnostic output after aliasing, variable substitution, command 
substitution, and filename generation, and just prior to 
execution. This capability is useful for watching the progress of a 
script and for debugging scripts—as the first line of your file, you 
would include the line 


Set Echo 1 
{Echo} is initially set to 0. 


When {Test} is set to a nonzero value, the command interpreter 
executes built-in commands and scripts, but not tools or 
applications. {Test} is useful for checking the control flow in 
command files. (It’s most useful if {Echo} is also nonzero.) {Test} 
is initially set to 0. 


This variable tells the Shell which command to execute when the 
ellipsis character (Option-semicolon) is present anywhere in a 
command line. The Startup file sets this variable to 
"Commando". This variable allows the development of similar 
tools whose output is to be executed by the Shell. If the variable is 
not set, then the ellipsis character is removed from the 
command line and normal execution proceeds. {Commando} 
must be exported if scripts are to use Commando. 

(continued) 


Variables 


Table 5-3 (continued) 
Variables defined In the Startup file 


Variables referenced by the editor 


{CaseSensitive} 


{Tab} 


{WordSet} 


{(PrintOptions} 


Any nonzero value specifies case-sensitive pattern matching. 
{CaseSensitive} is initially set to 0 (that is, false). You can also set 
{CaseSensitive} in the “Find and Replace” dialog boxes.. (See 
Chapter 3.) 


Default tab setting for new windows (initially 4). You can also set 
{Tab} in the “Format...” dialog available from the Edit menu. 


The set of characters that constitute a word to the editor (for Find 
and Replace menu commands, and for word selection by 
double-clicking). By default, {WordSet} is set to the characters 
a—z, A-Z, 0-9, and _ (underscore). If a character is not in the 
list, the editing commands regard it, like a blank, as a break 
between words. 


Options used by the Print Window and Print Selection menu 
commands. Initially set to "-h". (The -h option prints pages 
with headers. For more information on possible print options, 
see the Print command in Part IL.) 


Pathnames for libraries and include files 


{AIncludes} 


{CIncludes} 


{CLibraries} 


{Libraries} 


{PInterfaces} 


{PLibraries} 


{RIncludes} 


The directories to search for assembly-language include files, 
referenced by the Assembler. Initially set to 
"{MPW}AIncludes:". 


The directories to search for C include files, referenced by the C 
Compiler. Initially set to "{MPW}CIncludes:". 


The directory that contains C library files. Initially set to 
"“(MPW}CLibraries:". 


The directory that contains shared library files. Initially set to 
"{MPW}Libraries:". 


The directories to search for Pascal interface files, referenced by 
the Pascal Compiler. Initially set to "{MPW}PInterfaces:". 


The directory that contains Pascal library files. Initially set to 
“(MPW}PLibraries:". 


The directory that contains Resource Compiler (Rez) include 
files. Initially set to "{MPW}RIncludes:". 
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Parameters to scripts 


When a script is executed, its parameters automatically set the value of certain Shell 
variables. These variables are explained in Table 5-4. 


Table 5-4 
Parameters to scripts 


{0} Name of the currently executing script. 

{1}, {2},...{72} First, second, and mth parameter passed to the current script. 
(These values are null for commands entered interactively.) 

{#} Number of parameters (excluding the command name). 

{Parameters} Equivalent to {1} {2} ...{7}. 


{"Parameters"} Equivalent to "{1}" "{2}" ..."{}". This form should be used if 
the parameters could contain blanks or other special characters. 


The {Parameters} variable is especially useful when the number of parameters is 
unknown. The quoted forms, such as "{1}" or {"Parameters"}, are usually preferable 
to the unquoted forms because, after variable substitution, {1}, {2}, and so on could 
contain blanks or other special characters. For example, consider the Line script 
(which is useful with error messages as explained earlier in this chapter under 
“Executable Error Messages”): 


Find "{1}" "{Target}" # Find line n in the target window. 


Open "{Target}" # Make the target window the active a 
# (top) window. 


This script takes one parameter, a line number. Parameter {1} is quoted to handle the 
case where Line is called without any parameters. In this case the value of {1} is the 
null string, and without the quotes the {1} would completely disappear, leaving the 
name of the target window as the only parameter to Find. The quotes ensure that at 
least a null string is sent to Find as its first parameter—this is essential, because the 
window name must be the second parameter. Also notice that the {Target} variable is 
quoted, because it’s a filename that might contains blanks or other special 

characters. (For more information on quoting rules, see “Quoting Special 
Characters” later in this chapter.) 


Defining and redefining variables 
The following commands are used to define and modify variables: 


Set name value Assigns the string value to variable name. 


Set mame Writes the value of variable name to standard output. 

Set Writes a list of all variables and their values to standard output. 
Unset name Removes the definition of variable name. 

Unset Removes the definition of ail variables in the current scope. (For 


an explanation of the scope of a variable, see the next section.) 


Caution 

Removing all variables in the outermost scope can have serious consequences. 
For example, the Shell uses the variable {Commands} to locate MPW tools and 
other commands. The Assembler and Compilers use other variables to help 
locate include files. Some variables, such as {Boot}, cannot be reinitialized 
without restarting MPW. 


Variables 


Defining a variable and making it available for use by scripts and programs involves 
two separate steps: 


1. You can define a variable with the Set command. Note that variables are local to 
the script in which they are defined—a variable definition ceases to exist when its 
command file terminates. 


2. You can pass a variable to scripts and tools with the Export command. After you 


export a variable, nested scripts can reference that variable, and may override its 
value locally—but any redefinition is strictly local, and terminates when the script 


terminates. It’s impossible to affect the value of a variable in an enclosing script. 
(See Figure 5-1.) 


Exporting variables 
The Export command makes variables available to scripts and tools: 


Export name... Exports the named variables. 

Export Writes the list of exported variables to standard output 
Unexport name... Removes specified variables from the list of exported variables. 
Unexport Writes the list of unexported variables to standard output. 


You can define a variable globally by setting its value in the Startup file and exporting 


it Figure 5-1 illustrates how Export works. 


### UserStartup File ### 
Set var X 
Export var 


# (var) = 'xX! 
ACommandFile 


### ACommandFile ### 
Set Var Y 

Export var 
AnotherCommandFile 


### AnotherCommandFile ### 
# (var) = 'Y' 

Set var Z 

Export var 

# (var) = '2!' 


# (var) = 'X! 


Figure 5-1 
Trafficking in variables 


«* Note: You can use the Execute command to execute a script without creating a 
new scope for variables, exports, and aliases. The Shell “executes” the Startup, 
Suspend, Resume, and Quit scripts, and Startup uses Execute to run the 
UserStartup script. For more details about Execute, see Part II. 
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Command substitution 


Command substitution causes a command to be replaced by its output. You can 
specify command substitution by enclosing one or more commands in back 

quotes ( ~...~ ). The backquote key is located at the upper-left corner of the original 
Macintosh keyboard; it is located near the space bar of the newer keyboards. When 
the command is executed, the standard output of the enclosed commands replaces 
the ~...~. Command substitution can form part of a word, a complete word, or several 
words. Command substitution is not done within “hard” quotes (that is, the standard 
single quotes '...'). 


“> Note: If the standard output of the enclosed commands contains return 
characters, the returns are replaced by blanks. If the output ends with a return, 
this return is discarded. 


For example, the command 


Echo The date is ‘Date 


echoes the parameters, replacing the Date command with its output, as follows: 


The date is Wednesday, October 22, 1987 10:40:00 PM 


The following example duplicates the files whose names are output by the Files 
command: 


Duplicate ‘Files -t MPST MyDisk:* "{MPW}Tools" 


“Files -t MPST MyDisk:~ is replaced with a string of filenames of type MPST 
(that is, MPW tools) before the Duplicate command is executed; these files are then 
copied to the folder {MPW}Tools. This command is useful because the Files 
command allows you to specify files with a certain type or creator, which you can’t do 
with wildcard operators. 


Quoting special characters 


There are numerous characters that have special meanings to the MPW Shell. 
Normally, the Shell performs the action indicated by the special character—but you 
can disable a character’s special meaning (that is, include it as a literal character) by 
quoting it. You commonly need quotes when specifying filenames that contain 
blanks or other special characters, or when searching for the literal occurrence of a 
special character. See also “Pattern Matching” in Chapter 6. 


Quoting special characters 


Table 5-5 lists all of the special symbols recognized by the Shell. 


Table 5-5 
Special characters and words 


Character Meaning Where described 


Space “Structure of a Command” 
Tab 


Return Separates commands. 

; Separates commands. 

| Separates commands, piping output to input. 
&& Separates commands, executing the second 

if the first succeeds. 

1 | Separates commands, executing the second 
if the first fails. 

Command grouping; grouping in filename 
generation. 


Separates words 
Separates words 


“Structure of a Command” 
(Table 5-1) 


Invokes Commando. 

The ellipsis must be obtained by using the 
Option-semicolon key sequence; mot three 
periods. 


“Invoking Commando 
Dialogs” in Chapter 4 


“Structure of a Command” 


In this section (Table 5-7) 


# Comments. 


Escape character: quotes the 

subsequent character. 

Quotes all special characters, except "..." 

Quotes all special characters, except d, {, " 
and ~ 

Quotes all special characters, except d, {, ~ 
and / 

Quotes all special characters, except 0, {,> 
and \ 


IVINVV VA 
Vv 


IV 


Variable substitution. 
Command substitution. 


Matches a single character in filename 
generation. 
Matches any string in filename generation. 


Character list in filename generation. 

Zero or more repetitions in 

filename generation. 

One or more repetitions in filename 
generation. 

Specified number of repetitions in filename 
generation. 


Input file specification. 

Output file specification. 

Output file specification (append). 
Diagnostic file specification. 
Diagnostic file specification (append). 


Chapter 5: Using the Command Language 


“Variables” 
“Command Substitution” 


“Filename Generation” 
in this chapter and 
“Pattern Matching” in 
Chapter 6 


“Redirecting Input 
and Output” 
(Table 5-11) 


You can literalize a character by preceding it with the Shell escape character, 0 
(Option-D), or by including it within the quote symbols '...', "...", /.../, or \...\. The 
escape character, 0, quotes a single character only; the other quote symbols may be 
used to quote part or all of a word. These symbols are described in Table 5-6. 


Table 5-6 
Quotes 


fea “Hard quotes”: Take the enclosed string literally—no substitutions 
occur. The quotes are removed before execution. 


eee “Soft quotes”: Take the enclosed string literally. dc, variable 
substitutions, and command substitutions occur. The quotes are 
removed before execution. 


/.../or\...\. Regular expression quotes: Normally used to enclose regular 
expressions. Take the entire string literally, including the quote 
characters—the / or \ characters are mot removed. Variable 
substitutions and command substitutions occur. '...', "...", and d 
have their usual meanings—however, they are not removed. 


Single quotes, double quotes, and d are removed before parameters are passed to 
programs (unless they are themselves enclosed in quotes). For example, here is how 
you could define an AddMenu that compiles a C program in the active window: 


Wrong: AddMenu Extras "C Compile" C "{Active}" 
Right! AddMenu Extras “"C Compile" 'C "{Active}"' 


The first example won’t work because the {Active} variable will be expanded when the 
menu is added (it should be expanded when the menu item is executed). The 
second example is correct—when the AddMenu command is executed, the single 
quotes defeat variable expansion, they are then stripped off before the item is 
actually added. The double quotes remain, in case the pathname of the active 
window happens to contain any special characters. 


** Note: When quoting spaces (as in filenames), you'll usually use double quotes 
(soft quotes), to permit variable and command substitution. 


Slashes (or backslashes) are used to pass regular expressions as parameters to 
commands, without filename expansion occurring. For example, 


Search /procs/ Sample.p 


This command searches the file Sample.p for any string beginning with the 
characters “proc”. (See “Pattern Matching” in Chapter 6 and the description of the 
Search command in Part II.) 


Table 5-7 
Special escape conventions 


dc Escape character: Take the single character c literally. The four escape 
conventions that follow are exceptions to this rule. 


OReturn _—_ Return is discarded, allowing you to continue a command onto the next 


line. 
on Inserts a return character. 
at Inserts a tab character. 
of Inserts a form feed character. 
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How commands cre interpreted 


When you send text to the command interpreter (by pressing the Enter key or the 
equivalent), the following sequence of steps is performed: 


1 


7. 


. Alias substitution. 
2. 


Evaluation of control constructs. (This means that control constructs can’t be 
produced by command substitution but can have aliases.) 


. Variable substitution, command substitution. All variables Cunquoted or quoted 


with "...", /.../, or \...\ ) are replaced with their value. All commands enclosed in 
~,..” Cunquoted or quoted with "...", /.../, or \...\) are replaced with their output. 
If the ellipsis is found, Commando is executed and the command is replaced by 
the output of Commando. 


. Blank interpretation. After variables and commands have been substituted, the 


command text is divided into individual words separated by blanks. A blank is an 
unquoted space or tab. 


Note: The following symbols are normally considered separate words, whether or 
not they are set off by blanks: 
; | | | && () < > >> > >> 


Within expressions (used with If and Evaluate), all operators are considered 
separate words, unless they are quoted—see “Structured Commands” in this 
chapter. 


. Filename generation. A word that contains any of the unquoted characters ?, =, [, 


*,| +, or « after variable substitution is considered a filename pattern. The word is 
replaced with an alphabetically sorted list of the filenames that match the pattern. 
Cf no filename is found that matches the pattern, an error results.) 


. Input/output redirection. Because this step is performed last, variable 


substitution, command substitution, and filename generation can all be used to 
form the filenames used in I/O redirection. 


Execution. 


Any part of this process can be suppressed by using quotes as described in the 
previous section. Remaining single and double quotes are removed prior to 
execution. 
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Structured commands 


Structured commands (listed in Table 5-8) override the normal sequential execution 
of commands. They can be used interactively and within scripts. They may be nested 
arbitrarily deeply (subject to a limitation on stack space). The entire structured 
command is read before execution begins. All structured commnds are built into the 
MPW Shell. 


Caution 


After the Sheil “executes” an opening parenthesis or the opening word of a 
Begin. If. For, or Loop command, It will not execute any subsequent commands 
until a matching closing parenthesis or End word Is encountered. While It Is 
waiting for the end of the command, the status panel of the Worksheet window 
will contain the left parenthesis character, (, or the command name. You can 
abort the entire structured command by typing Command-period. 


The status value for a structured command is the status of the last command executed 
within the structured command (except for the Exit command, which lets you set 
your own status value). 


“+ Note: Expressions (used in If, Break, Continue, and Exit) are defined in the 
section following the table. 


Table 5-8 
Structured commands 


(command...) Parentheses are used to group commands for conditional 
execution, pipe specifications, and input/output specifications. 


Begin...End Begin 
commana... 
End 


Like parentheses, Begin and End group commands for 
conditional execution, pipe specifications, and input/output 
specifications. 


tae If expression 
command... 
[Else If expression 
command...) ... 
{Else 
commana... | 
End 


If... executes the commands following the first expression whose 
value is true (that is, nonzero and non-null). At most one of the 
lists of commands is executed. If none of the commands is 
executed, If returns a status value of 0. 


For... For name In word... 
commana... 
End 


For... executes the enclosed commands once for each word from 
the “In word...” list. For each iteration, a variable of the form 

{ tame} represents the current value from the word... list. (See 
the examples below.) 


(continued) 
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Table 5-8 (continued) 
Structured commands 


Loop...End Loop 
commana... 
End 


This command repeatedly executes the enclosed commands. 
The Break command is used to terminate the loop. 


Break Break [If expression ] 


Break terminates execution of the immediately enclosing For or 
Loop. If the expression is present, the loop is terminated only if 
the expression evaluates to true (nonzero and non-null). 


Continue Continue [ If expression ] 


Continue terminates this iteration of the immediately enclosing 
For or Loop and continues with the next iteration. If the 
expression is present, the Continue is executed only if the 
expression evaluates to true (nonzero and non-null). 


Exit Exit [ number] [ If expression | 


Exit terminates execution of the script in which it appears. If 
number is present, it is returned as the status value of the script; 
otherwise, the status of the last command executed is returned. If 
the expression is present, the script is terminated only if the 
expression evaluates to true (nonzero and non-null). (You can 
also use Exit interactively, to terminate execution of all 
previously entered commands.) 


The return characters in the command definitions above are significant; a return must 
appear at the end of each line as shown above, or be replaced by a semicolon (;). 


The following keywords are recognized when they appear unquoted as the first word 
of a command: 


Begin For Tf Else Loop End Break Continue Exit 


The keyword “In” is recognized when it appears unquoted following For; the keyword 
“If” is recognized when unquoted following Else, Break, Continue, and Exit. These 
keywords are not considered special in other contexts and need not be quoted. 


“* Note: These keywords can’t be produced as a result of variable substitution or 
command substitution. 


You can apply conditional execution (&& and | |), pipe specifications (|), and 
input/output specifications (<, >, >>, 2, and 22>) to entire structured commands 
(that is, to Begin...End, If...Else...End, For...End, and Loop...End, and to 
commands within parentheses). The operator should appear following the End or 
closing parenthesis. For example, you can collect the output of a series of commands 
and redirect it as follows: 


Begin 
Echo Good day 
Echo Sunshine 
End > OutputFile 


Inpul/output specifications are discussed later in this chapter. Each of the structured 
commands is described in detail in Part II. 
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Control loops 
The For and Loop commands are used for looping. 


The For...End command executes the enclosed commands once for each word in the 
“In word...” list. The current word is assigned to variable name, so you can 
reference the current word by using the Shell variable notation, (zame}. For 
example, 


For File In =.c 
C “(File}" ; Echo "{File}" compiled. 
End 


The Loop command provides unconditional looping—you’ll need to use the Break 
or Exit commands to terminate the loop. You can use the Continue command to 
continue with the next iteration. 


For example, the script below runs a command several times, once for each 
parameter: 


### Repeat - Repeat a command for several parameters ### 
# 


# Repeat command parameter... 
# 
# Repeat command once for each parameter in the parameter 
# list. Options can be specified by including them in 
# quotes with the command name. 
# 
Set cmd "{1}" 
Loop 
Shift 
Break If (#} == 
{cmd} "(1}" 
End 


In this example, the Shift command (explained in the next section) is used to step 
through the parameters, and the Break command ends the loop when all the 
parameters have been used. Using the script Repeat, you could compile several C 
programs, with progress information, using the command 


Repeat 'C -p' Sample.c Count.c Memory.c 
Repeat might also be used to set the font and font size for all the open windows: 


Repeat 'Font Courier 10' ‘Windows’ 
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Processing command parameters 


In addition to the commands introduced in Table 5-8, there are several other 
commands that are highly useful in scripts. The following commands are used to 
display or modify parameters: 


Echo [ parameters... } Writes its parameters, separated by blanks and 
terminated by a return, to standard output 


Parameters [ parameters... | Writes its parameters, including its name, to 
standard output. One parameter is written per line, 
preceded by the parameter number in braces and a 
space. A return is written following the last 
parameter. 


Shift [ number] Renames the parameters by subtracting number 
from the parameter number; that is, parameters 
number +1, number +2, and so on are renamed 1, 
2, and so on. If number is not specified, the default 
value is 1. The variables {1}, {2}...{n}, {#}, 
{Parameters}, and {"Parameters"} are all affected. 
Shift does not affect parameter {0} (the command 
name). 


Echo and Parameters are useful for checking how your parameters will behave before 
actually passing them to a command (for example, to check how your quotes are 
working out). For example, 


Parameters "=" 


For an example of how the various structured commands can work together, see 
“Sample Scripts” at the end of this chapter. 
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Expressions 


Expressions are used in the If, Break, Continue, and Exit commands. They’re also 
used in the Evaluate command, which returns the result of an expression. 


Table 5-9 lists the expression operators in order of decreasing precedence. Some 
operators have more than one representation; these equivalent symbols are listed on 
a single line. Groupings indicate operators of the same order of precedence. 


Table 5-9 
Expression operators in order of decreasing precedence 


Operator 


I. 
2: 


(expr) 


/ && 
oe 


NOT — 


DIV 
MOD 


IA 


IV 


OR 


Operation 


Expression grouping 
Unary negation 
Bitwise negation 
Logical NOT 
Multiplication 
Division 

Modulus division 


Addition 
Subtraction 


Shift left 
Shift right 


Less than 

Less than or equal to 
Greater than 

Greater than or equal to 


Equal 

Not equal 

Equal pattern (regular expression) 
Not equal pattern (regular expression) 


Bitwise AND 
Bitwise XOR 
Bitwise OR 
Logical AND 
Logical OR 
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All operators group from left to right. Parentheses can be used to override the 
operator precedence. Null or missing operands are interpreted as zero. The result of 
an expression is always a string representing a decimal number. Relational operators 
return the value 1 when the relation is true and the value 0 when the relation is false. 


Logical operators: The logical operators !, NOT, 7, &&, AND, | |, and OR interpret 
operands of value 0 or null as false; and nonzero, non-null operands as true. 


Numbers: Numbers may be either decimal or hexadecimal integers representable by 
a 32-bit signed value. Hexadecimal numbers begin with either $ or 0x. Every 
expression is computed as a 32-bit signed value. Overflows are ignored. 


String operators: The operators ==, !=, =~, and !~ compare their operands as 
strings. All others operate on numbers. 


Comparing text patterns: The =~ (equal pattern) and !~ (not equal pattern) 
operators are like == and != (which compare two strings), except that =~ and !~ are 
used for comparing a string with a text pattern. The right-hand side is a regular 
expression against which the left-hand operand is matched. For example: 


If "({1}" !~ /#,[acp] / 
Echo Filename must end with .a, ¢, or .p 
End 


*» Note: The regular expression in the above example must be enclosed in the 
regular expression quotes, /.../. See Chapter 6 for more information about 
regular expression syntax. 


If the regular expression contains the tagging operator ®, then, as a side effect of 
evaluating the expression, Shell variables of the form {®m} containing the matched 
substrings are created for each tag operator in the expression. (For an example, see 
the implementation of a wildcard rename command, under the description of the 
Rename command in Part II.) 


Use of special characters: Within expressions in the If, Break, Continue, Exit, and 
Evaluate commands, the following Shell operations are disabled: 

O filename generation 

QO conditional execution (1! and &&) 

C pipe specifications (1) 

Q input/output specifications (>, >>, >, 22, and <) 


=? 


This allows the use of many expression operators that would otherwise have to be 
quoted. In the case of If commands, the conditional execution or I/O specification 
should come after the End word. For other commands that contain expressions, you 
can specify conditional execution or I/O redirection by enclosing the command in 
parentheses. For example, 


(Evaluate {1} + (2}) 2 Errors 
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Filename generation 


After variables have been substituted, an unquoted word that contains any of the 
characters 


? 1 [ * + « 
is considered a filename pattern. The word is replaced with an alphabetically sorted 


list of filenames that match the pattern. An error is returned if no filename is found 
that matches the pattern. 


You can specify a group of file (or window) names with the “wildcard” notation given 
in Table 5-10. 


Table 5-10 
Filename generation operators 


? Matches any single character (except return or colon). 


= Matches any string of zero or more characters (except 
return or colon). 


[ characterList | Matches any character in the list. 


[— characterList | Matches any character not in the list. 


. 0 or more repetitions of the preceding character or 
character list @* is the same as =). 


+ 1 or more repetitions of the preceding character or 
character list. 


«number of repetitions» | Specified number of repetitions of the preceding 
character or character list. 


Note: The pattern matching is case insensitive. 


Note also: The pathname separator (:) must appear explicitly in the pattern—the : character 
will never be substituted for ?, =, or [...]. 


These special characters are the same regular expression operators used in 
editing commands. For a complete discussion of regular expressions, see Chapter 6. 


Naturally, you need to be careful with these wildcard operators. The Parameters and 
Echo commands are very useful for double-checking which filenames a command 
will generate. For example, before giving the command 


Delete *.c.0 
you might want to run the command 
Parameters *.c.0 


This command lists your “.c.o” files to standard output so that you can make sure you 
really want to delete them all. 


“» Note: Wildcard characters only generate names that match existing filenames; 
they do not create new files. For example, the following attempt to rename files 
will not work: 


Rename *.obj 3.0 


An example of how to perform a wildcard rename can be found under the 
description of the Rename command in Part II. 
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Redirecting input and output 


All built-in commands, scripts, and tools are provided with three open files: 
standard input, standard output, and diagnostic output (Figure 5-2). By default, 
standard input comes from the console (the window where the command is 
executed); standard output and diagnostics are returned to the console, immediately 
following the command. 


Standard 
output 


Standard 
input 


Diagnostic 
output 


Figure 5-2 
Standard input and output 


You can override these default assignments with the <, >, >>, 2, and 22 symbols 
described in Table 5-11. Note that input and output specifications are interpreted by 
the Shell; they are not passed to commands as parameters. Parentheses (or the 
Begin and End commands) can be used to group commands for input/output 
specifications. 


Table 5-11 

I/O redirection 

< name Standard input is taken from name. 

> name Standard output replaces the contents of name. File name is created if it 


doesn’t exist. 


>> name Standard output is appended to name. File name is created if it doesn’t 
exist. 


2 name Diagnostic output replaces the contents of mame. File name is created if 
it doesn’t exist. 


22 name Diagnostic output is appended to name. File name is created if it 
doesn’t exist. 
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Files and windows are treated identically—when given a name, the system looks first 
for an open window. Input and output can also be applied to selections: 


QO § indicates the current selection (in the target window). 
O name.§ indicates the current selection in window name. 


From the point of view of a command running within the Shell environment, input 
always comes from the standard input file and output goes to the standard output file. 
The command doesn’t need to know whether standard input happens to be text from 
a file, from a window, a selection, or typed in from the keyboard. For example, in 
the statement 


Program > OutputFile 


the string “> OutputFile” is interpreted by the Shell and is not passed as a parameter 
to the command—this process is completely invisible to the command. 


I/O specifications also apply to scripts. The standard input, standard output, and 
diagnostic output files provided to a script become the defaults for commands in the 
file. 


In addition to the sections later in this chapter, you'll find more on input and output 
in “Standard I/O Channels” in Chapter 13. 


Standard input 


By default, standard input is supplied by typing text and pressing Enter, or by 
selecting text that is already on the screen and pressing Enter. You can redirect 
standard input with the < operator. Note, however, that most commands that read 
standard input also accept a filename parameter. For example, the following two 
commands have the same result: 


Catenate < Sample.c 
Catenate Sample.c 


The Alert command reads from standard input if no message is supplied as a 
parameter to the command, but Alert doesn’t accept filenames as parameters. Thus 
input redirection is the only way to cause Alert to read input from a file. 


Alert Errors # Display Alert box containing the word Errors 
Alert < Errors # Display Alert box containing the contents 
# of the file Errors. 


Many commands, including the Assembler and Compilers, optionally read 
standard input to allow input to be read from a pipe (1) or entered interactively, as 
explained in the next section. 
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Terminating input with Command-Enter 


Many commands read from standard input if no filename is specified. For example, 
if you execute the command 


Asm 


the Assembler will begin reading from standard input—that is, you can enter text to 
it, and it will process each line as you enter it 


You can repeatedly enter text to a program that reads standard input, by typing or 
selecting text and pressing Enter. You indicate end-of-file by holding down the 
Command key and pressing Enter. For example, after you execute the command 


Catenate >> {Worksheet } 


the Catenate command will be running (its name will appear on the status panel at the 
bottom of the window). You can now enter data from the keyboard or select and 
enter text from various windows, and ali of it will be concatenated to the Worksheet 
window. Command-Enter indicates end-of-file and terminates the command. 


Standard output 


By default, standard output appears in the window in which the command was 
executed (that is, the console), immediately following the command. When 
commands are executed from menus, standard output appears following the 
selection in the active window. You can redirect standard output with the > and >> 
Operators. For example, 


Catenate Filel File2 > CombinedFile 


The Catenate command concatenates File2 to Filel—but instead of appearing in the 
active window, output is sent to the file named CombinedFile. If window 
CombinedFile is open on the desktop, its contents are overwritten. Otherwise, file 
CombinedFile is replaced (or created if it doesn’t exist). 


The >> operator appends standard output to the end of a selection, window, or file. If 
the named file doesn’t exist, a new file is created. For example, 


Catenate § >> AFile 


appends the contents of the current selection in the target window to AFile. (If the 
command was entered in the active window, the current selection is the selection in 
the target window.) You can also specify a selection in a named window: 


Catenate Sample.c.§ >> AFile 
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Diagnostic output 


By default, a command’s diagnostic output also appears immediately after the 
command, interleaved with standard output. The diagnostic output of commands 
executed from menus appears following the selection in the active window. You can 
redirect diagnostic output exactly as you redirect standard output, except that you use 
the operators 2 and 22 in place of > and >>. You may find it useful to have all error 
reporting appear in a separate window set aside for that task. For example, in 

Figure 5-3, the Assembler has been run, and error and progress information has 


been appended to a window called “Errors”. 


& File Edit Find Mark Window Directory Build 


Hse -p Sample.a >> Errorg 


COEF HO:MPw:AExamples:Errors 


...continuing with Sample.a 
..tneluding HO: MPW:Alneludes:QuickEqu.a 
.. continuing with Sample.a 
.. including HO: MPH: Alncludes: SysEqu.a 
... continuing with Sample.a 
QUICKORAW 
GLOBALOATA 
SETUPMENUS 
SHOWABOQUTMED I ALOG 
DOCOMMAND 
SAMPLE 


Elapsed time: 22.46 saconds. 


Assembly complete - no errors found. 4535 lines. 


Figure 5-3 
Redirecting diagnostic output 
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Pseudo-filenames 


Pseudo-filenames are a set of device names that you can use in place of filenames, 
but that have no disk files associated with them. Any command can open a pseudo- 
filename as a file. These device names are most commonly used for I/O redirection. 


Table 5-12 shows the available pseudo-filenames. 


Table 5-12 
Pseudo-filenames 


Dev:Console = Always refers to the current console device. The console is the 
default source of input and the default destination of output—that 
is, the active window where a command is entered and its output 
displayed. 


Dev: Null Null device. If you read from Dev:Null, it immediately returns end- 
of-file. If you write to Dev:Null, output is thrown away. 


Dev:StdIn Standard input. 

Dev:StdOut Standard output. 

Dev:StdErr Diagnostic output. 

The last three names, StdIn, StdOut, and StdErr, are used to explicitly represent 


input and output. You can use these specifications, for example, to send a 
command’s output and diagnostics to the same file: 


Search /NULL/ =.c > Found 2 Dev:StdOut 


Because the Shell opens standard input, standard output, and diagnostic output in 
the order they appear, file Found is opened first, then diagnostic output is redirected 
to the same file. The following command has the same effect: 


Search /NULL/ =.c 2 Found > Dev:StdErr 


However, if the filename and pseudo-filename specifications are simply reversed, 
the result is quite different: 


Search /NULL/ =.c 2 Dev:StdOut > Found 


This command redirects diagnostic output to the previous standard output (probably 
the active window), then redirects output to file Found. 


Pseudo-filenames are especially useful in a script when you want to do something like 
sending standard output to the diagnostic output. Here are some examples: 


Echo “An error message." >> Dev:StdErr 
Echo “HELP !" >> Dev:Console 


Dev:Null is useful in scripts when you want to throw away diagnostic output. For 
example: 


Eject 1 2 Dev:Null 


This command ejects the disk in drive 1; if no disk is in drive 1, the script continues to 
run silently. (Note that you would also need to set {Exit} to 0—see “Variables” earlier 
in this chapter.) 
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Editing with the command language 


Almost all menu functions have equivalents in the command language. In most 
respects, there is no difference between the menu items and their command- 
language equivalents. The primary difference is that with the com mand language, 
you enter commands in the active (frontmost) window, while the editing command 
acts on a selection in another window. You can explicitly name a window as a 
parameter to the command. If you don’t specify a window, the command acts on the 
target window. 


For example, to use command-language techniques to edit the file Sample.a, you 
must first open that file, and then click on another window, such as the Worksheet 
window, to make it the active window. You enter your commands in the active 
window, as shown in Figure 5-4. When you select text in the active window, it’s 
highlighted in the normal Macintosh fashion. In other windows, selected text is 
indicated by dim highlighting (outlining), as shown in the target window in 
Figure 5-4. 


@ File Edit Find Mark Window Directory Build 


Sa HD:MPW:Worksheet Seed 


KO} 
i 


3 MP 


i HO:MPW:ARExamples:Sampie.a 


MOVE.L (A7) ,appletlenuk Leave extra copy of handle on K> H 
MOYE.L (A7) ,-(A7) stack for AddResMenu Hf 
CLR -(A7) Install Apple menu in menu bar 
urnsertienu ; Inserttlenu(appletienul, 0); 
MDVE.L #'DRVYA' ,-(A7) Add DA names to Apple menu 
AddRestlenu : AddRestlenu(appletienuH, 'DRYR‘') 


: tH 


suBQ 


04,47 Read File menu from resource 
#fileID ,-(A7) file 


Figure 5-4 
Text highlighted In the active window and target window 


Editing commands generally act on a selection. (The Find command simply creates 
a selection—“DRVR’” in this example.) 


The § metacharacter (Option-6) is the current selection character—it signifies the 
current selection in a window. For example, the following command erases from the 
current selection or insertion point in the target window to the end of the window: 


Clear §:;00 


The infinity character, e (Option-5), is a selection operator that indicates the 
end of a window, as described in Chapter 6. For interactive editing, press 
Command-Delete to clear to the end of a file. 
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Defining your own menu commands 


The AddMenu and DeleteMenu commands are for adding and deleting menu items. 
The AddMenu command takes three parameters: the menu name, the item name, 
and the command text. For example, 


AddMenu Find 'Top of Window/U' 'Find « "{Active}"™! 


This command adds a “Top of Window” item to the Find menu, with the keyboard 
equivalent Command-U. When you select the menu item, the corresponding 
commands are executed. (The Top of Window item moves the insertion point to the 
top of the active window.) 


Invoking a user-defined menu item is the same as entering the command text from a 
window—variable substitution and command substitution are performed normally. 
Note, however, that the text of the menu command is processed twice—once when 
the AddMenu command itself is executed, and again whenever the menu item is 
executed. This means that you have to be especially careful in your use of quotes. The 
mysteries of quoting are explained earlier in this chapter in “Quoting Special 
Characters,” together with further AddMenu examples. You should also pay 
particular attention to the section “How Commands Are Interpreted.” For further 
information, and more examples, see the AddMenu command in Part II. 


Sample scripts 


The following examples use most of the Shell’s features to illustrate how you can 
extend the MPW Shell with your own commands. 


“AddMenuAsGroup” 


The following script adds an extra feature to the AddMenu command: 


# AddMenuAsGroup - AddMenu, grouping user defined menu items: 
# 

# AddMenuAsGroup [{ menuName [ itemName [{ command ]]} 

# 

# AddMenuAsGroup duplicates the functionality of the AddMenu 
# command, adding a disabled divider before the first user- 

# defined menu items in the File, Edit, and Find menus. 

# 

Unalias 

Set Exit 0 


Set CaseSensitive 0 
Tf ({#} == 3) AND ("{1}" =~ /File/ OR "(1}" =~ /Edit/ @ 


OR "{1}" =~ /Find/) 
If “AddMenu "{1}"* == 1 # If this is the first addition 
# in {1}, 
AddMenu "{1}" "(-" "" # add the group divider 
End 
End 


AddMenu ("“"Parameters"} 
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When adding menu items to the predefined menus, it’s nice to add a disabled dotted 
line item to separate the new menu items from the original ones. The script above 
automatically adds the separator before the first new item in the File, Edit, and Find 
menus, the only predefined menus that can be modified by using AddMenu. If you 
put this script in a file named AddMenuAsGroup, the following alias will override the 
built-in AddMenu command: 


Alias AddMenu AddMenuAsGroup 


si i, Cas 


The following script extends the C command by making it possible to compile a 
number of specified files: 


# CC - Compile a list of files with the C compiler 

# 

# CC [options..] [file...] 

# 

# Note that the options and the files may be intermixed, and 

# that all options apply to all the files. The individual C 

# commands are echoed to diagnostic output as they are executed. 
# 

Unalias 

Set Exit 0 


Set CaseSensitive 0 
Set options "" 
Set files "" 
Set exitStatus 0 
Loop 
Break If (#} == 0 
If "{1}" =~ /-[(diosu] / # options with a parameter 
Set options “{options}) '{1}' '{2)'" 
Shift 2 
Else If "{1})" =~ /-=/ # other options 
Set options “(options} '{1}'" 
Shift 1 
Else 
Set files "{files} '{1}'" 
Shift 1 
End 
End 
For i in (files} 
C {options} "{i}" || Set exitStatus 1 
End 
Exit (exitStatus} 
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Chapfer 6 


Advanced Editing 


This chapter describes the editing operations available as built-in commands, 
including the use of regular expressions. These commands enable powerful find- 
and-replace functions, and make it possible to automate editing operations by using 
Scripts. 


Menu commands for editing are described in Chapter 3. For a full description of the 
use of the command language, see Chapter 5. 


Editing commands 


The command language contains editing commands that duplicate the functions of 
many of the menu commands and provide additional capabilities. The editing 
commands are listed in Table 6-1. (They’re explained in detail in Part II.) 


Table 6-1 

Editing commands 

Adjust [-c count [-l spaces] selection [window] Adjust lines in a selection. 

Align [-c count] selection [window] Align text with first line of selection. 

Canon [ option... ] dictionaryFile [ inputFile... | Replace a file’s identifiers with canonical 
spellings given in dictionaryFile. 

Clear {[-c count] selection {windou] Delete selected text. 

Copy [-c count] selection (window) Copy selected text to the Clipboard. 

Cut [-e cound selection (|windou\ Copy selected text to the Clipboard and then 
delete the selection. 

Entab [ option... ] [ file... ] Convert runs of spaces to tabs. 

Find [-c count] selection (window! Find and select text. 

Font fontname fontsize (window... Change the font and/or size. 

Line [ number] Find line number. 

Mark [-y | -n] selection [window Assign the marker name to range of text 
selection selected in window. 

Markers [-q] [ window ...] Print list of all markers associated with 
window. 

Paste [-c count] selection [window] Replace selection with the contents of the 
Clipboard. 

Replace [-c count] selection replacement (window Replace selection with replacement. 

Revert [-y] [ window...] Revert window to last saved state. 

Tab number (window...) Set a window’s tab value to number spaces. 

Target name Make a window the target window. 

Translate source (destination! Convert selected characters. 

Undo [ window | Undo last command. 

Unmark name... window Remove the marker(s) name... from the list of 


markers available for window. 
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If no window parameter is specified, editing commands act on the target window 
(the second window from the front). Therefore, to edit the active window, you'll 
need to switch to another window for entering your commands. (The Target 
command makes a window the target window; the Shell variables {Active} and 
{Target} always contain the full pathnames of the current active and target windows.) 


Most editing commands take the following parameters: 


-c count You can specify a repeat count with the -c option—count is the number 
of times the command should be executed. Count may also be the 
infinity character, » (Option-5), which specifies that the operation 
should be repeated as many times as possible. 


selection Most editing commands act on a selection, either the current 
selection in the target window or another selection that you specify. 
First, an implicit Find is done to select the specified text. Then the text 
is modified. The selection syntax is defined in the next section. 


window The optional window parameter lets you specify the name of the 
window to be affected by a command, without changing the position of 
the affected window. 


A command modifies the selection only if there were no syntactic errors in the 
selection, and all regular expressions were matched. Commands run silently unless 
an error occurs. 


Selections 


Selection is a parameter to editing commands, and tells the command what text to 
select. A selection may be any of the following: 


O a line in a file (selected by line number) 
© a position in a file 
O a specific character pattern 


O a selection that begins and ends with any of the above 
As an example of the selection syntax, consider the definition of the Find command: 
Find [-c count] selection [window] 


Find takes a selection as an argument and selects the argument text (or sets the 
insertion point). An actual command might take the form 


Find /shazam/ 


This command finds and selects the first instance of the string “shazam” that appears 
after the current selection. (The slashes are used to enclose a pattern, a special case of 
a selection, as explained below.) No count is specified, so the command is executed 

once. No window name is specified, so the command operates on the target window. 


Selections 


Table 6-2 shows all of the selection operators. These are more fully explained in the 
sections following the table. 


Table 6-2 
Selection operators 


Current selection 


§ 


Line numbered selections 
n 
!n 
in 


Position (insertion point) 
e 


co 


Aselection 


selectionaA 
selectionin 
selectiontn 


Current selection in the target window (§ is Option-6 on 
the keyboard) 


Line number 7 

Line number 7 lines after the end of the current selection 
Line number 7 lines before the start of the current 
selection (j is Option-1) 


Position before the first character of the file Ce is 
Option-8) 

Position after the last character of the file (0 is Option-5) 
Position before the first character of selection (A is 
Option-J) 

Position after the last character of selection 

Position m characters after the end of selection 

Position m characters before the beginning of selection 


Pattern (characters to be matched) 


/pattern/ 


\ pattern\ 


Extended selection 
selection1:selection2 
marked selection name 


Grouping 
(selection) 


Pattern (regular expression)—search forward (see 
“Pattern Matching,” below) 
Pattern—search backward 


Both selections and everything in between 

The name of a marked selection may contain any 
characters except 

§ ! i ( ; >» co A ff \ 


Controls order of evaluation 


A formal definition of selections can be found in Appendix B. 


All of the operators group from left to right, and evaluation proceeds from left to 
right. The selection operators are listed below in order of precedence: 


/ and \ Everything within slashes is taken as a regular expression, and 
evaluated as explained below under “Pattern Matching.” 

C) Controls order of evaluation. 

A Indicates position. 

!andj Indicates position (! = after; ; = before). 


Joins two selections. 


Some examples will illustrate why it’s important to pay attention to the precedence of 


these operators: 


A/begin/!1 means 


rather than 


(A/begin/)!1 
A(/begin/!1) 


That is, the insertion point is located after the “b” of “begin” rather. than 


after the “n”. 


/oegin/:/end/!1 


means the selection 
rather than the position 


/begin/: (/end/!1) 
' (/bpegqin/:/end/)!1 
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That is, the character after “end” is included in the selection, as shown in Figure 6-1. 


& File Edit Find Mark Window Directory Build 
{5 HO:MPW:Worksheet === i 


o> 

mem 
I S| 

Ka Ree 


HO:MPW:PExamples:Memory.p 
O 


EMD; 


Figure 6-1 
A selection specification 


Current selection (§) 


The current selection character, § (Option-6), always indicates the current selection 
in a window. If no window is specified, § indicates the current selection in the target 
window. For example, consider the windows shown in Figure 6-2. 


& Fila Edit Find Merk Window Directory Build 


Ppepince 2 ou, 
q Mew shell oT 


ayfindow: WindowPtr ; 
BEGIN 


IF dCtl*.dCtlWindow = NIL THEN 
BEGIN 
GetPort (SavePort) ; 
myfindow := Get NewWindow(RsrcID(dctl) ,nil , POINTER(-1)); 
windowpeek(myWindow)%*.FindowKind := dCtl*.dCtlRefiium; ( show e DA 


dCtl*.dCtl¥indow := Ptr(myWindow); ({ let the desk manager know too ) 


Figure 6-2 
Selections in two windows 


Selections 
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The command 
Replace § dn 


would replace the current selection in the target window with a single return (newline) 
character. (“dn” is a special code for inserting a return—see “Inserting Invisible 
Characters” later in this chapter.) 


Note that the current selection is a dynamic quantity—it’s determined by the last 
subexpression evaluated, and thus represents the current state of a selection as it’s 
being calculated. For example, consider the command 


Find /if/:§!1:§!1 


At various points in the evaluation of the search string “/if/:§!1:§!1”, the current 
selection (§) has the following different values: 


Before calculation The pre-existing selection in the target window 
After “/if/” it” 
After “/if/:$!1” All characters from “if to (and including) the first 


character after the “if? 
After “/i£/:§!1:§$!1" — All characters from ‘if’ to (and including) the first 
two characters after the “if” 


Selection by line number 


If you give a number, unquoted by slashes, as a selection, it’s taken to be a line 
number. This may be an absolute line number, or a number of lines relative to the 
current selection. For example, to select line 3 of a file, you’d use the command ne 


Find 3 

This expression is equivalent to 
Find '3! 

but 

Find 3. or Find '3! 

is not equivalent to 

Find /3/ or Find \3\ 


The exclamation mark and inverted exclamation mark (! and ;) specify a number of 
lines after or before the current selection. The command 


Find !3 
selects a line that is 3 lines beyond the current selection. Note that the !7 notation 
specifies a line relative to the end of the current selection (that is, 7 lines past the line 


containing §A); {7 specifies a line relative to the start of the current selection (7 lines 
before the line containing A§). 
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Position 


A position is a special case of a selection. Position means the location of the 
insertion point only. The A character (Option-J) is used to convey position relative 
to a selection. For example, consider the commands 


Find 3 
Find A3 
Find 3A 


The first Find command selects the entire third line in the target file. The Find A3 
and Find 3A commands place the insertion point at the beginning and at the end 
of the third line. 


You can also use the ! and j operators to specify a position that’s a given number of 
characters from a selection: selection'n specifies a position m characters after 
selection, and selectionjn specifies a position m characters before selection. 


Notice that this leads to two different uses of the ! and j operators, as in the following 
example: 


Find !4!4 


The first “!4” indicates a selection that’s 4 lines beyond the current selection; the 
second “!4” indicates the position that’s 4 characters beyond the end of that 
selection. 


You can specify other positions in a file with the following special notation: 


° (Option-8) Position preceding the first character in file 
ce =». (Option-5) Position following last character in file 


Extending a selection 
A colon is used to join two selections. For example, 
Find /begin/:/end/ 


This command selects “begin”, “end”, and everything in between. (See Figure 6-1 
above.) Compare this command with 


Find /begin=end/ 


which looks for a begin-end pair on a single line. 


Selections 
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Markers 


A marker is a selection that has been given a name. A marker may be used as a 
selection variable. You can mark as many selections and insertion points as you 
wish. You can create markers directly by selecting text in a window and then clicking 
the Mark command in the Mark menu. See “Mark Menu” in Chapter 3 for more 
information on the interactive use of markers. This section describes the general 
behavior and programmatic use of markers. 


Markers may be as simple as a position in a window, but more often a marker names a 
range of positions. Markers have the special attribute of being able to remember 
their assigned position(s) even when you’re making editing changes all around them. 
For example, typing before marked text has the effect of moving both the text and its 
associated marker toward the end of the window. Editing “inside” the range of a 
marker will either increase or decrease the range of the marker depending on whether 
the editing was an insertion or deletion, respectively. 


Markers are “sticky.” For example, if an insertion point is marked and you type at that 
point, everything you type will be added to that marker. 


, If you delete the text encompassing a marker the marker will also be deleted. For 
example, if the string “xyz” is deleted and the character “y” is marked, the “y” 
marker will be deleted. However, if the string “xyz” itself is marked as “y”, deleting 
the string “xyz” will result in marker “y” being reduced to an insertion point. 


Markers are associated with individual windows. When you switch between windows, 
the Mark menu is updated to reflect the markers of the new active window. 


Markers are persistent. They are saved in the resource fork of the file you are editing, 
just like the font, tab, and other information about the window. 


You can create or delete Markers programmatically by using the following three Shell 
commands: 


Mark [-y | -n] selection [windowl Assign the marker name to range of text 
selection selected in window. 


Markers [ window] Print list of all markers associated with 
window. 
Unmark name...window Remove the marker(s) mame... from the list 


of markers available for window. 


For example, to mark the currently selected text in the target window with the name 
“Function B” and to replace any previous marker of that name, you would type 


Mark -y § ‘Function B' 


The new marker name will appear in the Mark menu. You might remove the marker 
later by using the Unmark command: 


Unmark 'Function B' "{Target"} 


Th‘ command would remove that marker from the target window. 
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The new selection syntax allows you to jump to a marker programmatically and 
automatically select the output of a script for a user. To jump to a marker named 
“george”, you might use a command similar to the following: 


Find george 


To automatically select the output of a script for a user, you could use a script similar 
to the following: 


Mark §A X_ #Mark the start of output 
Make #Run your Make command 
Find X #Select the output of Make 


For further details on the Shell commands for markers, see Part II. 


Pattern 


A pattern may be either a literal text pattern or a regular expression (defined in the 
next section). You specify a pattern between the /.../ and \...\ delimiters. Forward 
slashes indicate a search forward, and back slashes indicate a search backward. A 
forward search begins at the end of the current selection and continues to the end of 
the file. A backward search begins at the start of the current selection and continues 
to the beginning of the file. For example, the command 


Find /myString/ 


searches forward for the literal expression “mystring”. (Recall that to specify case- 
sensitive pattern matching, you need to set the Shell variable {CaseSensitive}, or 
select the “Case Sensitive” menu item.) 


“» Note: To locate the insertion point at the beginning of the target window, for 
instance before executing a Find command, you can use the command 


Find « 


In fact, this command is so useful that you may want to add it as a menu 
command—see the example under the AddMenu command in Part I. 


Pattern matching (using regular expressions) 


Regular expressions are a shorthand language for specifying text patterns. Regular 
expressions are used in editing commands, in the Search command (which searches 
one or more files for occurrences of a pattern), and in If and Evaluate expressions 
following the =~ and !~ operators. Most of the regular expression operators may also 
be used in filename generation. 


Regular expressions are always used within the pattern delimiters /.../ or \...\. 


A special set of metacharacters, called regular expression operators, is used in 
regular expressions (and in filename generation). The regular expression operators 
are listed in Table 6-3. 


Pattern matching (using regular expressions) 


Table 6-3 
Regular expression operators 


Cc Any character matches itself (unless it’s one of the 
special characters listed below) 


dc Defeat special meaning of following character (c is 
taken literally) except 


on = return 
ot = tab 
of = form feed 


Vict Literalize enclosed characters 


wf Literalize enclosed characters, except d, {, and ~ 

? Any single character (other than return) 

= Any string of 0 or more characters, not containing a 
return 

[character...] Any character in the list 

[-character...] Any character not in the list (4 is Option-L on the 
keyboard) 

regularExpr* Regular expression 0 or more times 

regularExpr+ Regular expression 1 or more times 

regularExpr« n>» Regular expression m times (« is Option-\; » is 
Option-Shift-\) 

regularExpr«n,» Regular expression m or more times 

regularExpr«n, ,Ny» Regular expression n, to m times 

CregularExpr) Grouping 

CregularExpn®n Tagged regular expression (where 0 < n< 9) 

regularExpr, regularExpr> regularExpr, followed by regularExpr, 

e regularExpr Regular expression at beginning of line 

regularExpree Regular expression at end of line 


These characters are considered special in the following circumstances: 


d Special everywhere except within single quotes (...') 
252 * +f « €) Special anywhere except within [...], '...', and "..." 

® Special only after a right parenthesis, ) 

° Special as first character of entire regular expression 
oo Special as last character of entire regular expression 
/ \ Special if used to delimit a regular expression 


Their precedence (from highest to lowest) is as follows: 
Peto 

Zee. * + [{] « ® 

3. concatenation 

4,¢ © 


A formal definition of regular expressions can be found in Appendix B. The rest of 
this section describes the use of regular expressions for describing selections. 
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Character expressions 


In the simplest case, regular expressions consist of literal characters enclosed in 
slashes. For example, 


/what the ?/ 


Notice one complication, however—f the literal character happens to be one of the 
regular expression operators (such as “?”), it will be specially interpreted rather than 
taken as a literal character. If you want to specify a literal character that happens to 
have a special meaning within the context of regular expressions, you'll have to 
precede it with the escape character, 0, or enclose it in quotes. The character d has 
the effect of “literalizing” the character that follows it. For example, to find the literal 
expression given above, you would use one of the following commands: 


Find /what the d?/ 
Find /what the '?'/ 
Find /'what the ?'/ 


You could also use double quotes, that is "...". 


Wildcard operators 


In addition to literal characters, regular expressions can include the operators ?, = 
(Option-X), and [ ], which are used as follows: 


? Any character other than return 


ms Any string not containing return, including the null string (this 
is the same as ?*) 


[characterList| Any character in the character list (as defined below) 
[5 characterList| Any character not in the list 


These operators are also used as wildcards in filename generation. (You can also use 
the *, +, and «...» operators in filename generation—see “Filename Generation” in 
Chapter 5.) 


A character list is an expression consisting of one or more characters enclosed in 
square brackets ([...]). It matches any character found in the list. The case-sensitivity 
of characters in the list is governed by the {CaseSensitive} variable (which you can set 
or unset by toggling the Case Sensitive check box in the Find or Replace dialog 
boxes). A list may consist of individual characters or a range of characters, specified 
with the minus sign (-). For instance, the following two commands are equivalent: 


Find /{ABCDEF] / 
Find /(A-F]/ 


You can also mix the two notations: 
Find /[(0-9A-FS$]/ 


«* Note: This command specifies any of the characters 0 through 9, A through F, 
and $. To specify the ] or - character, place it at the beginning of the list or 
literalize it with the escape character, d. 


The negation symbol, — (Option-L), lets you specify any character mot in the list. For 
example, 


Find /[-mA-2]/ 


This example specifies all characters except the letters A through Z. (To specify the > 
character itself, place it anywhere in the list other than the beginning, or literalize it 
by preceding it with the escape character, 0.) 


Pattern matching (using regular expressions) 


Repeated instances of regular expressions 


The asterisk character (*) matches zero or more occurrences of the immediately 
preceding regular expression. The plus sign (+) matches one or more occurrences of 
an expression. For example, the command 


Find /[{0-9]+/ 
will find any string of one or more digits. 


You can also specify an expression that occurs an explicit number of times with the 
«mn» notation: 


regularExpr«n>» Regular expression 7 times 
regularExpr«n,» Regular expression at least 7 times 
regularExpr«n,,nr» Regular expression at least 7, times and at most mp, times 


For example, 
Replace -c ~ /' '«4,»/ dt 


This command finds any string of four or more spaces, and replaces it with a tab. 
(The -c option specifies a repeat count of “infinity”; that is, it replaces all 
occurrences of the selection to the end of the document) 


Tagging regular expressions with the ® operator 


The ® (Option-R) operator tags a regular expression between parentheses. This 
operator is useful with the Replace command, for example, in reformatting tables of 
data. Consider a table with two columns of numbers separated by spaces or tabs: 


123 456 
123 456 
123 456 
123 456 


etc. 

The following Replace command switches the order of the two columns: 
Replace -c « /((0-9]+)@1[ dt]+((0-9]+)@2/ '®2 @1' 
Translated into English, this expression means 

[0-9]+ Match one or more characters in the set “0” to “9”. 


({0-9]+)®1 Remember that selection (the expression enclosed in 
parentheses) as ®1. 


{ dt]+ Next, match at least one space or tab. 


({0-9]+)®2 Then match one or more characters in the set “0” to “9” and 
remember it as ®2. 


'®2 @®1'! Finally, replace the whole matched string with what was 
remembered as ®2, a space, and what was remembered as ®1. 


Note: The quotes are stripped off, as explained under “Quoting 
Special Characters” in Chapter 5. The ® operator itself can 
be disabled only with the escape character, d. 
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After this sequence is executed, the table will look like this: 


456 123 
456 123 
456 123 
456 123 
etc. 


Matching a pattern at the beginning or end of a line 


In the context of regular expressions, the « metacharacter (Option-8) means that the 
subsequent expression must be matched at the beginning of a line. For example, the 
regular expression 


/emain/ 


will match a line that begins with “main” but not a line that begins with “space main”. 
The beginning of a line is either the first character after a return or the first character 
of the file. 


Likewise, the co metacharacter means that the previous expression must be matched 
at the end of a line. The regular expression 


/maines/ 


will match a line that ends with “main” but not a line that ends with “main space”. 
The end of a line is either the last character of a line prior to the return, or the end of 
the file. 


Notice that ¢ and oo have another meaning within selections. Within a pattern, they 
indicate the beginning and end of a /ine. Within a selection, they indicate the 
beginnning and end of the /ile. 


Inserting invisible characters 


You can use the Shell escape character, d, to insert the following special characters in 
text: 


on return 
ot tab 
of form feed 


*» Note: The “Show Invisibles” menu item shows the invisible space, tab, and 
return characters in a file. 


For more information on the escape character, see “Quoting Special Characters” in 
Chapter 5. 


Pattern matching (using regular expressions) 


Note on forward and backward searches 


Forward and backward searches aren’t always completely symmetrical. For example, 
consider the command 


Find /2?*/ 


This command finds zero or more occurrences of any character other than a return. 
The first time you execute this command, if the current selection is not at the end of a 
line, some range of characters will be selected. However, in subsequent invocations, 
the selection will hang at the end of the line—only an insertion point will be left at the 
end of the line. This is because the * metacharacter matches zero occurrences and 
the search starts with the character following the current selection—in this case, the 
insertion point preceding a return. A backward search of the form 


Find: \2?*\ 


will never hang at the beginning of a line. This is because a backward search begins 
with the first character to the left of the current selection and so has the effect of 
jumping over a return after encountering it. 


Some useful examples 


This section shows some examples of complex use of regular expressions. 


Transforming DumpObj output 


The DumpObj command, described in Part II, formats the contents of an object file. 
This example shows how to transform a DumpObj listing, such as the following, back 
into valid assembly code. 


000000: 4EBA O6F8 SON ea. tay 7% JSR *+SO6FA ¢ 6004282A 
000004: 4EBA O4EA TN sexer JSR *+SO04EC 7 60042620 
000008: 3B7C 0014 FCC4 ‘';|....' MOVE.W #$0014, $FCC4 (A5) 

OOOOOE: 266D 0010 ‘ém..' MOVEA.L $0010 (A5),A3 

000012: 2653 '"&S' MOVEA.L (A3) ,A3 

000014: OCSB 0000 OM ares CMPI.W #$0000, (A3) + 

000018: 6600 0008 Eee! BNE *+SO00A ; 60042152 
00001C: 3A1B era MOVE .W (Ast +; DS 

OOOO1E: 6600 0010 oe ne BNE *+$0012 7 60042160 
etc. 


You could position the insertion point at the beginning of the code and use the 
following Replace command: 


Replace -c «© /?«41»/ "dtdt" # replace everything up to the 
# instruction with 2 tabs 


However, the previous command works only because DumpObj happens to place the 
instruction at column 42. The following example, by defining some Shell variables, 
works regardless of the exact column layout: 


Set hex "(0-9A-F] «4, 6»" # 4 to 6 characters in the set 0-9 and A-F 
Set space "[{ dt]+" # 1 or more spaces or tabs 
Set chars "dd'?+dd'" # 1 or more of any character between @ 


# single quotes 
Replace -c » /(hex}: ({space} {hex})«1l,3»(space}(chars}{space}/ "“dtdt" 
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Finding a whole word 


The following example illustrates how you could find an exact match for a C identifier 
that you had previously defined in the variable {idend: 


Set tokensep "(ma~zA-Z_0-9]" # a token separator is any character 
# not in the set a-z, A-Z,_, or 0-9 


Set CaseSensitive 1 # set to "true'"—the case of each 
# character must match 


The following Find command is not quite right, because it selects not only the 
matched identifier, but also the token separator on each side of the identifier: 


Find /{tokensep} {ident} {tokensep}/ 


The following Find command selects only the matched identifier. It accomplishes 
this by adding 1 to the starting position of the selection (Aselection!1), and using 
that as the starting point for a new selection that extends to the beginning of the next 
token separator: 


Find A/({tokensep} {ident} (tokensep}/!1:A/({(tokensep}/ 
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Chapter 7 


Editing Resources 
With ResEdit 


The chapter describes ResEdit, a stand-alone application for editing resources. 


“+ Note: As in Inside Macintosh, resource types are shown within single quotes; for 
example, 'STR ' (that is, STRspace). The quotes are not part of the name. 


About ResEdit 


ResEdit is an interactive, graphically based application for manipulating the various 
resources in a Macintosh application. It lets you create and edit all standard resource 
types except 'CODE', and copy and paste all resource types (including 'CODE'). 
ResEdit actually includes a number of different resource editors: There is a general 
resource editor, for editing any resource in hex and ASCII format, and there are 
several individual resource editors for specific types of resources. You can also 
create your own resource editors to use with ResEdit. 


Uses 


ResEdit is especially useful for creating and changing graphic resources such as 
dialog boxes and icons. For example, you can use ResEdit to put together a quick 
prototype of a user interface and try out different formats and presentations of 
resources. Anyone can quickly learn to use ResEdit for translating resources into a 
foreign language without having to recompile the program. You can use ResEdit to 
modify a program’s resources at any stage in the process of program development. 


Once you have created or modified a resource with ResEdit, you can use the Resource 
Decompiler, DeRez, to convert the resource to a textual representation that can be 
processed by the Resource Compiler, Rez. You can then add comments to this text 
file or otherwise modify it with the Shell editor. (Rez and DeRez are fully described in 
the next chapter.) 


Extensibility 


A key feature of ResEdit is its extensibility. Because it can’t anticipate the format of all 
the different types of resources that you might use, ResEdit has been designed so that 
you can teach it to recognize and parse new resource types. 


There are two ways that you can extend ResEdit to handle new types: 


O You can create templates for your own resource types. ResEdit lets you edit most 
resource types by filling in the fields of a dialog box—this is the way you edit 
'BNDL' and 'FREF' resources, for example. The layout of these dialog boxes is 
determined from a template in ResEdit’s resource file, and you can.add templates 
to edit new resource types. Resource templates are described later in this chapter. 


QO You can also program your own special-purpose resource picker and/or editor 
and then add it to ResEdit. The resource picker is the code that displays all the 
resources of one type in the resource type window. The editor is the code that 
displays and allows you to edit a particular resource. These pieces of code are 
separate from the main code of ResEdit. A set of Pascal routines, called ResEd, is 
available for this purpose—see the MPW Pascal 2.0 Reference for information. 
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Using ResEdit 


From the MPW Shell, you can start ResEdit by entering the command 
ResEdit 


(This assumes, of course, that ResEdit is in the Applications folder, or elsewhere in 
the search path defined by the {Commands} variable.) From the Finder, you can just 
select and open the ResEdit icon. ResEdit displays a window that lists the files and 
folders for each disk volume currently mounted (Figure 7-1). 
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Figure 7-1} 
Disk volume windows 


Working with files 


To list the resource types in a file, select and open the filename from the list. (You 
can select a name by clicking on it or by typing one or more characters of the name.) 


When a directory window is the active window, the File menu commands act as 
follows: 


New Creates a new file. 

Open Opens the selected file or folder. (This is the same as double-clicking on 
the name.) 

Close Closes the volume window. CThis is the same as clicking the close box.) If 


it’s a 3.5-inch disk, the disk is ejected. 
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Get Info Displays file information and allows you to change it. Figure 7-2 is an 
example of the File Info window for the MPW Shell file. 


CiLocked ([JInvisible {Bundle C] System 
| C)On Desk [Bozo (C) Busy CJ Changed 
1 ()Cached [J Shared & Inited 
1 (Always switch launch 


1 CJFile Busy (J File Lock (File Protect 


Created (4/22/87 9:42:00 AM 
Modified |4/22/87 9:42:00 AM 


Resource fork size = 237282 bytes 
Data fork size = 0 bytes 


Figure 7-2 
A File Info window 


Transfer Allows you to transfer to an application other than the application that 
launched ResEdit. (This is an alternative to the Quit command.) 


Quit Quits from ResEdit and returns to the MPW Shell (or Finder). 


Warning 


You can edit any file shown in the window, including the System file and ResEdit 
itself. However, it's dangerous to edit a file that’s currently in use. Edif a copy of 
the file instead. (For example, edit the System file on a non-booft volume.) 


ResEdit will recognize a new disk when it’s inserted, and handle multiple drives. Note 
that you can also use ResEdit to copy or delete files: 


Q To delete a file, select the file and choose Clear from the Edit menu. 


Q To copy a resource file, you must select all of its resources and copy them. Then 
paste them into a new file. (File attributes are not automatically copied by this 
operation—you must set them via the Get Info command.) ResEdit cannot copy a 
data fork. 


Working within a file 


When you open a file, a window displays a list of all the resource types in that file 
(Figure 7-3). While this window is the active window, you can create new resources, 
copy or delete existing resources, and paste resources from other files. 


o 


«* Note: The resources are displayed by a resource picker. The general resource 
picker displays the resources by type, name, and ID number, there are also 
special resource pickers for some resource types. (For example, the 'ICON' 
resource picker displays the icons graphically.) 
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Figure 7-3 
A ResEdit file window 


When a file window is the active window, the File menu commands have the following 
effects: 
New Creates a new resource in the open file. 


Open Opens a window displaying all resources of the resource type 
selected. (Select the resource type by clicking on it or by typing its 
first character.) 


Note: If you hold down the Option key while opening a resource 
type, the resource window will open with the general resource 


picker. 

Open General Opens the general resource picker. 

Close Closes the file window and asks if you want to save the changes you 
have made. 


Note: If you’ve made changes, you should not reboot before 


closing. 

Revert Changes the resource file back to the version that was last saved to 
disk. 

Quit Quits from ResEdit. 


When a file window is the active window, the Edit menu commands have the 
following effects: 


Cut Removes all resources of the resource types selected, placing them 
in the ResEdit scrap. 

Copy Copies all resources of the resource types selected into the ResEdit 
scrap. 

Paste Copies the resources from the ResEdit scrap into the file window’s 


resource type list. 


Clear Removes all resources of the resource type selected, without 
placing them in the ResEdit scrap. 


Duplicate Creates duplicates of all resources of the resource types selected, 
and assigns a unique resource ID number to each new resource. 
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Working within a resource type 


Opening a resource type produces a window that lists each resource of that type in the 
file (Figure 7-4). This list will take different forms, depending on the particular 
resource picker; if you hold down the Option key during the open, the general 

‘ resource picker is invoked. 


MPW Shell 


ICN#'s from MPW Shell == 
ras 


Figure 7-4 
A resource type window 


When a resource type window is the active window, the File menu commands have 
the following effects: 


New Creates a new resource and opens its editor. 

Open Opens the appropriate editor for the resource you selected. 

Open a... Allows you to open an editor template of a different type. 

Open General Opens the general Chex) resource editor. 

Close Closes the resource type window. 

Revert Changes the file back to what it was before you opened the resource 
type window. 

Get Info Displays resource information and allows you to change it. 


Figure 7-5 is an example. 
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Figure 7-5 
A Get Info window for ICN#'s 
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When a resource type window is the active window, the Edit menu commands have 
the following effects: 


Undo Undoes the most recent editing command. Undo may or may not be 
selectable, depending on the specific editor in use. 

Cut Removes the resources that are selected, placing them in the ResEdit 
scrap. 

Copy Copies all the resources that are selected into the ResEdit scrap. 

Paste Copies the resources from the ResEdit scrap into the resource type 
window. 

Clear Removes the resources that are selected, without placing them in the 


ResEdit scrap. 


Duplicate | Creates a duplicate of the selected resources and assigns a unique 
resource ID number to each new resource. 


Editing individual resources 


To open an editor for a particular resource, either double-click on the resource or 
select it and choose Open from the File menu. One or more auxiliary menus may 
appear, depending on the type of resource you’re editing. Some editors, such as the 
'DITL' editor, allow you to open additional editors for the elements within the 
resource. All the editors use File and Edit menus similar to those described above, 
but operate on individual resources or individual elements of a resource, and hence 
vary in their appearance and function as explained below. 


If you hold down the Option key while opening a resource, the general data editor is 
invoked. This editor allows you to edit the resource as hexadecimal or ASCH data. If 
you hold down the Shift and the Option keys while opening, ResEdit shows you a list 
of all editors and templates. 


Caution 


Individual editors may not be appropriate for all resource types—inappropriate 
editors may cause system errors to occur. 


The menus for some of the editors are discussed below. The use of the editors not 
discussed here should be apparent when you run them. 


“* Note: The general data editor will not edit resources larger than 16K bytes; 
however, you can move larger resources with the Cut, Copy, Paste, and Clear 
commands as described above. 
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‘CURS' (cursor) resources 


For 'CURS' resources, the editor displays three images of the cursor (Figure 7-6). You 
can manipulate all three images with the mouse. 
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Figure 7-6 
Editing 'CURS' resources 


In Figure 7-6 the left image shows how the bulldozer cursor will appear. The middle 
image is the mask for the cursor, which affects how the cursor appears on various 
backgrounds. The right image shows a gray picture of the cursor with a single point in 
black—this point is the cursor’s hot spot. 


The Cursor menu contains the following commands: 


Try Cursor Lets you try out the cursor by having it become the cursor in use. 
(Restore Arrow restores the standard arrow cursor.) 


Data + Mask Copies the cursor image to the mask editing area. 


‘DITL' (dialog item list) resources 


For 'DITL' resources, the editor displays an image of the item list as your program 
would display it in a dialog or alert box. When you select an item, a size box appears 
in the lower-right corner of its enclosing rectangle so that you can change the size of 
the rectangle. You can move an item by dragging it with the mouse. 


If you open an item within the dialog box, the editor associated with the item is 
invoked, for an 'ICON', for example, the icon editor is invoked. If you hold down the 
Option key while opening, the general data editor is invoked. 
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The DITL menu contains the following commands: 


Bring to Front Allows you to change the order of items in the item list. Bring to 
Front causes the selected item to become the last Chighest 
numbered) item in the list. The actual number of the item is 
shown by the 'DITM'! editor. 


Send to Back Like Bring to Front, except that it makes the selected item the first 
item in the list—that is, item number 1. 


Grid Aligns the item on an invisible 8-pixel by 8-pixel grid. If you 
change the item location while Grid is on, the location will be 
adjusted such that the upper-left corner lies on the nearest grid 
point above and to the left of the location you gave it If you 
change the size, it will be made a multiple of 8 pixels in both 
dimensions. 


Use RSRC Rect Restores the enclosing rectangle to the rectangle size stored in 
the underlying resource. Note that this works on ‘ICON’, 'PICT', 
and 'CNTL' items only; the other items have no underlying 
resources. 


Use Full Window Adjusts the window size so that all items in the item list are visible 
in the window. 


‘FONT’ resources 


For 'FONT' resources, the editor window is divided into fourpanels: a character 
editing panel, a sample text panel, a character selection panel, and a set of 
MacDraw-like graphics tools. These are shown in Figure 7-7. 
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Figure 7-7 
‘FONT editor window 
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The character editing panel, on the left side of the window shows an enlargement of 
the selected character. You can edit it, as with FatBits in MacPaint, by clicking bits on 
and off. Drag the black triangles at the bottom of the character editing panel to set 
the left and right bounds (that is, the character width). The three triangles at the left 
of the panel control the ascent, baseline, and descent. 


The sample text panel, at the upper right, displays a sample of text in the font 
currently being edited. (You can change this text by clicking in the text panel and 
using normal Macintosh editing techniques.) 


The character selection panel is below the text panel. You can select a character to 
edit by typing it Cusing the Shift and Option keys if necessary), or by clicking on it in 
the row of three characters shown. (Click on the right character in the row to move 
upward through the ASCII range; click on the left character to move downward.) The 
character you select is boxed in the center of the row with its ASCII value shown below 
it Gn decimal). 


The graphic tools panel, directly below the character selection panel, offers a dozen 
or more of the familiar MacDraw-type tools including the hand mover, pencil, 
eraser, circles, and rectangles. In addition, a selection of colors is available. 


Caution 


Changing the ascent or descent of a character changes the ascent or descent 
for the entire font. 


Any changes you make in the character editing panel are reflected in the text panel 
and the character selection panel. Remember that you cannot save the changes until 
you close the file. 


You can also change the name of a font. The font name is stored as the name of the 
resource of that font family with size 0. This resource does not show up in the normal 
display of all fonts in a file. To display it, hold down the Option key while you open 
the 'FONT' type from the file window. You will see a generic list of fonts. Select the 
font with the name you wish to change, and choose Get Info. 
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'ICN#' (icon list) resources 


For 'ICN#' resources, the editor displays two panels in the window (Figure 7-8). The 
upper panel is used to edit the icon. It contains an enlargement of the icon on the left 
and an enlargement of the icon’s mask on the right. The lower panel shows, from left 
to right, how the icon will look unselected, selected, and open on both a white and a 
gray background. It also shows how the icon will appear in the Finder’s small icon 
view. 
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Figure 7-8 
ICN#' window 


To install a new icon for your application when you already have an old one in the 
Finder’s desktop file, follow these steps: 


1. Open the file called DeskTop. 


2. Open type 'BNDL' and find the bundle that belongs to your application. (This is 
the one that has your owner name in it.) Look through the bundle and mark down 
the type and resource ID of all resources bundled together by the bundle (that is, 
the 'ICN#'s and 'FREF's). 


3. Go back to the DeskTop window and remove these resources along with your 
'BNDL' and signature resource (the resource whose type is your application’s 
signature). 


4. Now close the DeskTop window, save changes, and quit ResEdit. Your new icon 
will be installed if you have the proper 'BNDL', 'FREF', and 'ICN#' resource 
numberings. 


“* Note: To see how 'BNDL', 'FREF', and 'ICN#' resources are interrelated, use 
ResEdit to look at those resources in an existing application such as the MPW 
Shell. 


Alternatively, you can rebuild the DeskTop file by holding down the Option and 
Command keys when entering the Finder. (This method is faster and easier, but you 
will lose your Finder Get Info comments; you will also lose folder names on a non- 
HFS volume.) 
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Creating a resource template 


You can customize ResEdit by creating new templates for your own resource types. 
The generic way of editing a resource is to fill in the fields of a dialog box—for 
example, this is the way you edit 'FREF', 'BNDL', and 'STR#!' resources. The layout of 
these dialog boxes is set by a template in ResEdit’s resource file. The template 
specifies the format of the resource and also specifies what labels should be put 
beside the editText items in the dialog box that’s used for editing the resource. You 
can find these templates by opening the ResEdit file and then opening the type _~ 
window for 'TMPL' resources. For example, if you open the template for 'WIND' 
resources (this is the 'TMPL' with name “WIND”), you'll see the template shown in 
Figure 7-9. 


TPLs from ResEdit 


205 TMPL "PICT" 10 = 22 from Residit B=] 
O 


B8ODDDSSeaeD 


Figure 7-9 

Window template data 

The window template, then, consists of the following: 

1. A RECT (4 words) specifying the boundary of the window. 


2. A word that is the procID for the window (DWRD tells ResEdit to display the word 
in decimal as opposed to hex). 


3. A Boolean indicating whether or not the window is visible. (BOOL is 2 bytes in the 
resource but is displayed as a radio button in the dialog window used for editing.) 


4. Another Boolean indicating whether or not the window has a close box. 


5. A long word that is the reference value (refCon) for the window. (DLNG indicates 
that it should be displayed in the editor as a: decimal number.) 


6. A Pascal string (PSTR), the title of the window. 
You can look through the other templates and compare them with the structure of 
those resources to get a feel for how you might define your own resource template. 


(These templates are equivalent to the resource type declarations contained in the 
{RIncludes} directory—refer also to the DeRez command in Part II.) 
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These are the types you have to choose from for your editable data fields: 
DBYT, DWRD, DLNG Decimal byte, word, long word 
HBYT, HWRD, HLNG Hex byte, word, long word 


HEXD Hex dump of remaining bytes in resource 

PSTR Pascal string Cength byte followed by the characters) 

LSTR Long string Cength long followed by the characters) 

WSTR Same as LSTR, but a word rather than a long word 

ESTR, OSTR Pascal string padded to even or odd length (needed for 
DITL resources) 

CSTR C string 

ECST, OCST Even-padded C string, or odd-padded C string (padded 
with nulls) 

BOOL Boolean 

BBIT Binary bit 

TNAM Type name (4 characters, like OSType and ResType) 

CHAR A single character 

RECT An 8-byte rectangle 

Hnnn A 3-digit hex number (where nnn < $900); displays nnn 


bytes in hex format. 


ResEdit will do the appropriate type checking for you when you put the editing dialog 
window away. 


The template mechanism is flexible enough to describe a repeating sequence of 
items within a resource, as in 'STR#', 'DITL', and 'MENU' resources. You can also 
have repeating sequences within repeating sequences, as in 'BNDL' resources. To 
terminate a repeating sequence, put the appropriate code in the template as follows: 


LSTZ 


LSTE List Zero—List End. Terminated by a 0 byte (as in 'MENU's). 


ZCNT 
LSTC 


LSTE Zero Count/List Count—List End. Terminated by a zero-based count that 
Starts the sequence (as in 'DITL' resources). 


OCNT 
LSTC 


LSTE One Count/List Count—List End. Terminated by a one-based count that 


Starts the sequence (as in 'STR#! resources). 
LSTB 


[Ste Ends at the end of the resource (no example exists in the given templates). 


The “list-begin” code begins the repeating sequence of items, and the LSTE code is 
the end. Labels for these codes are usually set to the string “*****” Both of these 
codes are required. 


Creating a resource template 


To create your own template, follow these steps: 
1. Open the ResEdit file window. 

. Open the 'TMPL' type window. 

. Choose New from the File menu. 


. Select the list separator (*****), 


Mm & WW N 


. Choose New from the File menu. You may now begin entering the /abel,type pairs 
that define the template. Before closing the template editing window, choose Get 
Info from the File menu and set the name of the template to the 4-character name 
of your resource type. 


6. Close the ResEdit file window and save changes. 


The next time you try to edit or create a resource of this new type, you'll get the dialog 
box in the format you have specified. 


Warning 


Changing resource templates (and hence resource type descriptions) can cause 
system crashes If you open older versions of a resource with a new template. 
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Chapier 8 


Resource Compiler 
and Decompiler 


In the Macintosh Programmer’s Workshop, you can build a resource graphically with 
ResEdit, or in text form with the Resource Compiler. This chapter explains the use of 
the Resource Compiler (Rez) and Resource Decompiler (DeRez). The command line 
syntax for Rez and DeRez is explained in Part II. General information on resource 
files is given in the Resource Manager chapter of Inside Macintosh. 


About the Resource Compiler and Decompiler 


The Resource Compiler, Rez, compiles a text file (or files) called a resource 
description file, and produces a resource file as output. The Resource Decompiler, 
DeRez, decompiles an existing resource, producing a new resource description file 
that can be understood by Rez. Figure 8-1 illustrates the complementary relationship 
between Rez and DeRez. 
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Figure 8-1 
Rez and DeRez 


The Resource Compiler can combine resources or resource descriptions from a 
number of files into a single resource file. The Resource Compiler also supports 
preprocessor directives that allow you to substitute macros, include other files, and 
use if-then-else constructs. (See “Preprocessor Directives” later in this chapter.) 


Resource Decompiler 


The DeRez tool creates a textual representation of a resource file based on resource 
type declarations identical to those used by Rez. (If you don’t specify any type 
declarations, the output of DeRez is in the form of raw data statements.) The output of 
DeRez is a resource description file that may be used as input to Rez. This file can be 
edited in the MPW Shell, allowing you to add comments, translate resource data to a 
foreign language, or specify conditional resource compilation by using the if-then- 
else structures of the preprocessor. You can also compare resources by using the 
MPW Compare command to compare resource description files. 


«* Note: MPW also includes a tool, ResEqual, which directly compares resource 
files. The source for ResEqual is located in the PExamples folder. 
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Standard type declaration files 


Three text files, Types.r, SysTypes.r, and MPWTypes.r, contain resource 
declarations for standard resource types. These files are located in the {RIncludes} 
directory, which is automatically searched by Rez and DeRez (that is, you can specify 
a file in (RIncludes} by its simple filename). These files contain definitions for the 
following types: 


Types.r Type declarations for the most common Macintosh 
resource types (‘ALRT’, 'DITL', 'MENU', and so on) 
SysTypes.r Type declarations for 'DRVR', 'FOND', 'FONT', 'FWID', 'INTL', 


and 'NFMT' and many others 
MPWTypes.r Type declarations for the MPW driver type 'DRVW' 


Using Rez and DeRez 


Rez and DeRez are primarily used to create and modify resource files. Figure 8-2 
illustrates the process of creating a resource file. 
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Figure 8-2 
Creating a resource file 


About the Resource Compiler and Decompiler 


Rez can also form an integral part of the process of building a program. For instance, 
when putting together a desk accessory or driver, you’d use Rez to combine the 
Linker’s output with other resources, to create an executable program file. (See 
Chapter 9 for details.) 


Structure of a resource description file 


The resource description file consists of resource type declarations (which can be 
included from another file) followed by resource data for the declared types. Note 
that the Resource Compiler and Resource Decompiler have no built-in resource 
types—you need to define your own types, or include the appropriate “.r” files. 


A resource description file may contain any number of statements, where a statement 
is any of the following: 


include Include resources from another file. 

read Read data fork of a file and include it as a resource. 

data Specify raw data. 

type Type declaration—declare resource type descriptions for 


subsequent resource statements. 


resource Data specification—specify data for a resource type declared in 
a previous type statement 


Each of these statements is described in the sections that follow. 


A type declaration provides the pattern for any associated resource data 
specifications by indicating data types, alignment, size and placement of strings, 
and so on. You can intersperse type declarations and data in the resource 
description file as long as the declaration for a given resource precedes any 
resource statements that refer to it. An error is returned if data (that is, a 
resource statement) is given for a type that has not been previously defined. 
Whether a type was declared in a resource description file or in an include file, you 
can redeclare it by providing a new declaration later in a resource description file. 


A resource description file can also include comments and preprocessor directives: 


= Comments can be included anywhere where white space is allowed in a resource 
description file, within the comment delimiters /* and */. Note that comments 
do not nest. For example, this is one comment: 


/* Hello /* there */ 


m= Preprocessor directives substitute macro definitions and include files, and 
provide if-then-else processing before other Rez processing takes place. The 
syntax of the preprocessor is very similar to that of the C-language preprocessor. 
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Sample resource description file 


An easy way to learn about the resource description format is to decompile some 
existing resources. For example, the following command decompiles only the 
'WIND' resources in the Sample application, according to the the type declaration in 
{RIncludes}Types.r. 


DeRez Sample -only WIND Types.r > DeRez.Out 


After executing this command, DeRez.Out would contain the following decompiled 
resource. 


resource 'WIND' (128, "Sample Window") { 
{64, 60, 314, 460}, 
documentProc, 
visible, 
noGoAway, 
0x0, 


“Sample Window" 
}; 


Note that this statement is identical to the resource description in the file Sample.r, 
which was originally used to build the resource. This resource data corresponds to 
the following type declaration, contained in Types.r: 


type 'WIND' ( 
rect; /* boundsRect */ 
integerdocumentProc, dBoxProc, plainDBox, /* procID */ 
altDBoxProc, noGrowDocProc, 
zoomProc=8, rDocProc=16; 


byte invisible, visible; /* visible */ 
fill byte; 

byte noGoAway, goAway; /* goAway */ 
fill byte; 

unsigned hex Longint; /* refCon */ 

pstringUntitled = "Untitled"; /* title */ 


}; 


Type and resource statements are explained in detail in the reference section that 
follows. 


Structure of a resource description file 
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Resource description statements 


This section describes the syntax and use of the five types of resource description 
statements: include, read, data, type, and resource. 


Syntax notation 


The syntax notation in this chapter follows the conventions given in the preface of 
this book. Additionally, the following conventions are used: 


O Words that are part of the resource description language are shown in Courier to 
distinguish them from other text. The Resource Compiler is not sensitive to the 
case of these words. 


O Punctuation characters such as commas (,), semicolons (;), and quotation marks 
C and ") are to be written as shown. If one of the syntax notation characters (for 
example, { or ]) must be written as a literal, it is shown enclosed by curly quotes 
C...”); for example, 


bitstring ‘[’ length ‘}’ 
In this case, the brackets would be typed literally—they do mot mean that the enclosed 
element is optional. 


O Spaces between syntax elements, constants, and punctuation are optional—they 
are shown for readability only. 


Tokens in resource description statements may be separated by spaces, tabs, returns, 
or comments. 


Special terms 


The following terms represent a minimal subset of the nonterminal symbols used to 
describe the syntax of commands in the resource description language: 


Term Definition 
resource-type long-expression 
resource-name _ String 
resource-ID word-expression 
ID-range ID{: ID] 


“* Note: Expression is defined later in this chapter under “Expressions.” 


A full syntax definition can be found at the end of this chapter and in Appendix D. 
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Include—include resources from another file 


The include statement lets you read resources from an existing file and include all 
or some of them. 


Syntax 


Include statements can have the following forms: 
O include (file [ resource-type [‘(’ resource-name | ID[:ID]‘)’!} ; 


Read the resource of type resource-type with the specified resource name or 
resource ID range in file. If the resource name or ID is omitted, read all resources 
of the type resource-type in file. If resource-type is omitted, read all the resources 
in file. 


O include file not resource-type ; 
Read all resources not of the type resource-type in file. 
O include /ile resource-typel as resource-type2 ; 


Read all resources of type resource-typel and include them as resources of 
resource-type2. 


O include file resource-typel ‘(’ resource-name | ID[:ID/‘)’ 
as resource-type2 ‘(’ ID [, resource-name | (, attributes... ]‘)’; 


Read the resource of type resource-typel with the specified name or ID range in 
file, and include it as a resource of vesource-type2 with the specified ID. You can 
optionally specify a resource name and resource attributes. (Resource attributes 
are defined below.) 


Some examples follow: 
include “otherfile"; /* include all resources from the file */ 
include “otherfile" 'CODE'; /* read only the CODE resources */ 


include "otherfile" 'CODE' (128); /* read only CODE resource 128 */ 


AS resource description syntax 


The following string variables can be used in the AS resource description to modify 
the resource information in include statements: 


$$Type Type of resource from include file. 
$$SID ID of resource from include file. 
$$Name Name of resource from include file. 


SSAttributes Attributes of resource from include file. 


For example, to include all DRVR resources from one file and keep the same 
information, but also set the SYSHEAP attribute: 


INCLUDE "file" ‘DRVR' (0:40) AS 
"DRVR' (SSID, $S$Name, $SAttributes | 64) ; 


The $$Type, $$ID, $$Name,and $$Attributes variables are also set and legal within 
a normal resource statement. At any other time the values of these variables are 
undefined. 
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Resource attributes 


You can specify attributes as a numeric expression (as described in the Resource 
Manager chapter of Inside Macintosh), or you can set them individually by 
specifying one of the keywords from any of the following pairs: 


Default Alternative Meaning 


appheap sysheap Specifies whether the resource is to be loaded 
into the application heap or the system heap. 


nonpurgeable purgeable Purgeable resources can be automatically 
purged by the Memory Manager. 


unlocked locked Locked resources cannot be moved by the 
Memory Manager. 


unprotected protected Protected resources cannot be modified by 
the Resource Manager. 


nonpreload preload Preloaded resources are placed in the heap as 
soon as the Resource Manager opens the 
resource file. 


unchanged changed Tells the Resource Manager whether a 
resource has been changed. Rez does not 
allow you to set this bit, but DeRez will display 
it if it is set. 

Bits 0 and 7 of the resource attributes are reserved for use by the Resource Manager 

and cannot be set by Rez, but are displayed by DeRez. 


You can list more than one attribute by separating the keywords with a comma (,). 


Read—read data as a resource 


The read statement lets you read a file’s data fork as a resource. 


Syntax 


read resource-type'(' ID [, resource-name | ([, attributes]')’ file; 


Description 


Reads the data fork from file and writes it as a resource with the type resource-type 
and the resource ID JD, with the optional resource name resource-name and 
optional resource attributes (as defined in the preceding section). For example, 


read 'STR ' (-789,"Test String", SysHeap, PreLoad) "Test8"; 
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Data—specify raw data 


Data Statements let you specify raw data as a sequence of bits, without any 
formatting. 


Syntax 


data resource-type ‘(’ ID [, resource-name } [, attributes... ]‘)’ ‘{’ 
data-string 


ee 


Description 


Reads the data found in data-string and writes it as a resource with the type resource- 
type and the ID JD, You can optionally specify a resource name, resource attributes, 
or both. 


For example, 


data 'PICT' (128) { 
S"4F35FF8790000000" 
S"FF234F35FF790000" 
}; 


“» Note: When DeRez generates a resource description, it uses the data statement to 
represent any resource type that doesn’t have a corresponding type declaration 
or cannot be disassembled for some other reason. 


Type—declare resource type 


A type declaration provides a template that defines the structure of the resource data 
for a single resource type or for individual resources. If more than one type 
declaration is given for a resource type, the last one read before the data definition is 
the one that’s used—this lets you override declarations from include files or previous 
resource description files. 


Syntax 


type resource-type {'‘(' ID-range‘)’] ‘{' 
type-specification... 
it 
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Description 


Causes any subsequent resource statement for the type resource-type to use the 
declaration { type-specification...}. The optional [D-range specification causes the 
declaration to apply only to a given resource ID or range of IDs. 


Type-specification is one of the following: 


bitstring [7] 
byte 
integer 
longint 
boolean 
char 
string 
pstring 
wstring 
cstring 
point 
rect 


cop I Zero fill 
align Zero fill to nibble, byte, word, or long word boundary 
switch Control construct (case statement) 


array Array data specification—zero or more instances of 
data-types 


These types can be used singly or together in a type statement. Each of these type 
specifiers is described in the sections that follow. 


“» Note: Several of these types require additional fields—the exact syntax is given in 
the sections that follow. 


You can also declare a resource type that uses another resource’s type declaration, 
by using the following variant of the type statement: 


type resource-type1['‘(’ ID-range'‘)’] as resource-type2 [(’ ID ')']; 
Data-type specifications 


Data-type statements declare a field of the given data-type. They can also associate 
symbolic names or constant values with the data-type. Data-type specifications can 
take three forms, as shown in the following example: 


type "XAMP' { /* declare a resource of type 'XAMP! */ 
byte; 
byte off=0, on=1; 
byte = 2; 


}; 


O The first byte statement declares a byte field; the actual data is supplied in a 
subsequent resource statement. 


Q The second byte statement is identical to the first, except that the two symbolic 
names “off? and “on” are associated with the values 0 and 1. These symbolic 
names could be used in the resource data. 


Q The third byte statement declares a byte field whose value is always 2. In this case, 
no corresponding statement would appear in the resource data. 


“* Note: Numeric expressions and strings can appear in type statements; they are 
defined later in this chapter under “Expressions.” 
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Numaric types: The numeric types (bitstring, byte, integer, longint) are 
fully specified as follows: 


[ unsigned ]} ( radix } mumeric-type [( =expr | symbol-definition... |; 


Q The unsigned prefix signals DeRez that the number should be displayed without a 
sign—that the high-order bit may be used for data and the value of the integer 
cannot be negative. The unsigned prefix is ignored by Rez but is needed by 
DeRez to correctly represent a decompiled number. Rez uses a sign if it is specified 
in the data. Precede a signed negative constant with a minus sign (—); $FFFFFF85 
and -$7B are equivalent in value. 


O Radix is one of the following string constants: 
hex decimal octal binary literal 
You can supply numeric data as decimal, octal, hexadecimal, or literal data. 


O Numeric-type is one of the following: 


bitstxring'[’length']’ Declare a bitstring of length bits (maximum 32). 


byte Declare a byte (8-bit) field. This is the same as 
bitstring(8]. 

integer Integer (16-bit) field. This is the same as 
bitstring[16]. 

longint Long integer (32-bit) field. This is the same as 
bitstring([32]. 


Rez uses integer arithmetic and stores numeric values as integer numbers. Rez 
translates booleans, bytes, integers, and longints to bitstring equivalents. All 
computations are done in 32 bits and truncated. 


An error is generated if a value won't fit in the number of bits defined for the type. 
The valid ranges for values of byte, integer, and longint constants are as 
follows: 


Type Maximum Minimum 
byte 255 -128 
integer 65535 ~32768 


longint 4294967295 -2147483648 


Boolean type: A Boolean is a single bit with two possible states: 0 (or false) and 1 
(or true). (True and false are global predefined identifiers.) Boolean values are 
declared as follows: 


boolean [ = constant | symbolic-value... |; 
Type boolean declares a 1-bit field; this is equivalent to 
unsigned bitstring(1] 


Note that this type is not the same as a Boolean variable as defined by Pascal. 
Character type: Characters are declared as follows: 

char [ = string | symbolic-value... }; 

Type char declares an 8-bit field (this is the same as writing string[1]). 


Here is an example: 
type 'SYMB' { 
char dollar = "S",percent = "%"; 
Me 
resource 'SYMB' (128) { 
dollar 
}; 
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String type: String data types are specified as follows: 
string-type [‘(’ length ‘]’] [= string | symbol-value...], 
String-type is one of the following: 


(hex] stxing Plain string (no length indicator or termination character is 
generated). The optional hex prefix tells DeRez to display it as a 
hex-string. String[m] contains n characters and is n bytes 
long. Type char is shorthand for string[1]. 


pstring Pascal string (a leading byte containing the length information 
is generated). pstring[m] contains 71 characters and is n+1 
bytes long. pst ring has a built-in maximum length of 255 
characters, the highest value the length byte can hold. If the 
string is too long to fit the field, a warning is given and the string 
is truncated. 


wstring Word string is a very large pst ring. Its length is stored in the 
first two bytes. Therefore, a wst ring can contain up to 65,535 
characters. Wstring[m] contains ™ characters and is m+2 bytes 
long. 


estring C string (a trailing null byte is generated). Cstring[7] 
contains m~1 characters and is 7 bytes long. A cst ring of 
length 1 can be assigned only the value "", because 
estring [1] has room only for the terminating null. 


Each may be followed by. an optional /Jength indicator in brackets ([7]). Length is an 
expression indicating the string length in bytes. Length is a positive number in the 
range 1 $ length < 2147483647 for string and cstring, and in the range 1 < /ength 
< 255 for pstring, and in the range 1 < length < 65535 for wstring. 


“* Note: You cannot assign the value of a literal to a string-type. 


If no length indicator is given, a pstring, wstring, or cstring stores the 
number of characters in the corresponding data definition. If a length indicator is 
given, the data may be truncated on the right or padded on the right. The padding 
characters for all string types are nulls. If the data contains more characters than the 
length indicator provides for, the string is truncated and a warning message is given. 


Warning 

A null byte within a cstring is a termination indicator and may confuse DeRez 
and C programs. However, the full string, Including the explicit null and any text 
that follows it, will be stored by Rez as input. 


Point and rectangle types: Because points and rectangles appear so frequently in 
resource files, they have their own simplified syntax: 


point [= potnt-constant | symbolic-value... }; 
rect [= rect-constant | symbolic-value... |; 


where 

point-constant = ‘('x-integer-expr, y-integer-expr ‘}' 

and 

rect-constant = ‘{'integer-expr, integer-expr, integer-expr, integer-expr ‘}’ 

These type-statements declare a point (two 16-bit signed integers) or a rectangle 


(four 16-bit signed integers). The integers in a rectangle definition specify the 
rectangle’s upper-left and lower-right points, respectively. 
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Fill and align types 


The resource created by a resource definition has no implicit alignment. It’s 
treated as a bit stream, and integers and strings can start at any bit. The fill and 
align type specifiers are two ways of padding fields so that they begin on a boundary 
that corresponds to the field type. align is automatic and £il1 is explicit. Fill and 
alignment generate zero-filled fields. 


Fill specification: The £il1 statement causes Rez to add the specified number of bits 
to the data stream. The fill is always 0. The form of the statement is 


fill fill-size [‘(’ length')']; 
where /fill-size is one of the following strings: 
bit nibble byte word long 


These declare a fill of 1, 4, 8, 16, or 32 bits (optionally multiplied by the /ength 
modifier). Length is an expression < 2147483647. 


The following fi11 statements are equivalent: 

fill word(2]; 

fill long; 

fiit bit [(32ye 

The full form of a type statement specifying a fill might be as follows: 
type 'XRES' ( data-type specifications; fill bit[2];}; 


“» Note: Rez supplies zeros as specified by fill and align statements. DeRez does 
not supply any values for £il1 or align statements; it just skips the specified 
number of bits, or until data is aligned as specified. 


Align specification: Alignment causes Rez to add fill bits of zero value until the data is 
aligned at the specified boundary. An alignment statement takes the following form: 


align align-size ; 
where align-size is one of the following strings: 
nibble byte word long 


Alignment pads with zeros until data is aligned on a 4, 8-, 16-, or 32-bit boundary. 
This alignment affects all data from the point where it is specified until the next 
align statement. 
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Array type 
An array is declared as follows: 
[ wide ] array [ array-name | ‘['length')'’] '{' array-list'}’; 


The array-list, a list of type specifications, is repeated zero or more times. The wide 
option outputs the array data in a wide display format (in DeRez)—the elements that 
make up the array-list are separated by a comma and space instead of a comma, 
return, and tab. Either array-name or [length] may be specified. Array-name is an 
identifier. 


If the array is named, then a preceding statement must refer to that array in a 
constant expression with the $$countof(array-name) function; otherwise DeRez 
will be unable to decompile resources of this type. For example, 


type 'STR#' { /* define a string list resource */ 
integer = $$Countof (StringArray) ; 
array StringArray { 
pstring; 
}; 
}e 


The $Scountof function returns the number of array elements (in this case, the 
number of strings) from the resource data. 


If [length] is specified, there must be exactly length elements. 


Switch type 


The switch statement specifies a number of case statements for a given field or 
fields in the resource. The format is as follows: 


switch ‘(’ case-statement... ‘}’; 
where a case-statement has the following form: 
case case-name : [ case-body ; ]... 


Case-name is an identifier. Case-body may contain any number of type 
specifications and must include a single constant declaration per case, in the 
following form: 


key data-type = constant 

Which case applies is based on the key value. For example, 

type 'DITL' { /* dialog item list declaration from Types.r */ 
.. type specifications... 
switch { /* one of the following */ 


case Button: 


boolean enabled, disabled; 
key bitstring{7] = 4; /* key value */ 
pstring; 


case CheckBox: 


boolean enabled, disabled; 

key bitstring(7] = 5; /* key value */ 
pstring; 

etc. 


}e 
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Sample type statement 
The following sample type statement is the standard declaration for a 'WIND' 
resource, taken from the Types.r file: 


type 'WIND' { 
rect; /* boundsRect */ 
integer documentProc, dBoxProc, plainDBox, /* procID */ 
altDBoxProc, noGrowDocProc, 
zoomProc=8, rDocProc=16; 
byte invisible, visible; /* visible */ 
fill byte; 
byte noGoAway, goAway; /* has close box*/ 
fill byte; 
unsigned hex longint; /* refCon */ 
pstring Untitled = "Untitled"; /* title */ 


3 


The type declaration consists of header information followed by a series of 
Statements, each terminated by a semicolon (;). The header of the sample window 
declaration is 

type 'WIND' 

The header begins with the type keyword followed by the name of the resource type 
being declared—in this case, a window. You may specify a standard Macintosh 
resource type, as shown in the Resource Manager chapter of Inside Macintosh, or 
you may declare a resource type specific to your application. 


The left brace .{). introduces the body of the declaration. The declaration continues 
for as many lines as necessary until a matching right brace (}) is encountered. You 
can write more than one statement on a line, and a statement may be on more than 
one line dike the integer statement above). Each statement represents a field in the 
resource data. Recall that comments may appear anywhere where white space may 
appear in the resource description file; comments begin with /* and end with */ as 
in C. 


An aside—symbol definitions: Symbolic names for data-type fields simplify the 
reading and writing of resource definitions. Symbol definitions have the form 


name = value [, name = value }... 


For numeric data, the “= value” part of the statement can be omitted. If a sequence 
of values consists of consecutive numbers, the explicit assignment can be left out—if 
value is omitted, it’s assumed to be one greater than the previous value. (The value is 
assumed to be zero if it’s the first value in the list.) This is true for bitstrings (and their 
derivatives, byte, integer, and longint). For example, 


integer documentProc, dBoxProc, plainDBox, 
altDBoxProc, noGrowDocProc, 
zoomProc=8, rDocProc=16; 


In this example, the symbolic names documentProc, dBoxProc, plainDBox, 
altDBoxProc, and noGrowDocProc are automatically assigned the numeric values 0, 
1, 2, 3, and 4. 


Memory is the only limit to the number of symbolic values that can be declared for a 
single field. There is also no limit to the number of names you can assign to a given 
value; for example, 


integer documentProc=0, dBoxProc=1, plainDBox=2, altDBoxProc=3, 
rDocProc=16, 
Document=0, Dialog=1, DialogNoShadow=2, ModelessDialog=3, 


DeskAccessory=16; 
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Resource—specify resource data 


Resource statements specify actual resources, based on previous type 
declarations. 


Syntax 


resource Yresource-type ‘(' ID[, resource-name | [, attributes}‘)’ ‘{’ 
| data-statement { , data-statement }... ] 
‘ } a ; 


Description 


Specifies the data for a resource of type resource-type and ID ID. The latest type 
declaration declared for resource-type is used to parse the data specification. Data- 
statements specify the actual data; data-statements appropriate to each resource 
type are defined in the next section. 


The resource definition causes an actual resource to be generated. A resource 
statement can appear anywhere in the resource description file, or even in a separate 
file specified on the command line or as an #include file, as long as it comes after 
the relevant type declaration. 


Data statements 


The body of the data specification contains one data statement for each declaration 
in the corresponding type declaration. The base type must match the declaration. 
Base type Instance types 


string string, cstring, pstring, wstring, char 
bitstring boolean, byte, integer, longint, bitstring 
rect rect 

point point 


Switch data: Switch data statements are specified by using the following format: 
switch-name data-body 
For example, the following could be specified for the 'DITL' type given earlier: 


CheckBox { enabled, "Check here" }, 


Array data: Array data statements have the following format: 


‘(' [ array-element[, array-element)...]‘}’ 


where an array-element consists of any number of data statements separated by 
commas. 


For example, the following data might be given for the 'STR#! resource defined 
earlier: 


resource 'STR#' (280) { 
{ "this", 
MS Ys 
wa". 


"test" 
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Sample resource definition 


This section describes a sample resource description file for a window. (See the 


Window Manager chapter of Inside Macintosh for information about resources in 
windows.) 


Here, again, is the type declaration given above under “Sample Type Statement”: 


type 'WIND' { 
rect; /* boundsRect */ 
integer documentProc, .dBoxProc, plainDBox, /* procID */ 
altDBoxProc, noGrowDocProc, 
zoomProc=8, rDocProc=16; 


byte invisible, visible; /* visible */ 

fill byte; 

byte noGoAway, goAway; /* has close box */ 
fill byte; 

unsigned hex longint; /* refCon */ 
pstring Untitled = "Untitled"; /* title */ 


d; 


Here is a typical example of the window data corresponding to this declaration: 


resource 'WIND' (128,"My window", appheap,preload) { /* Status report window */ 
{40,80,120,300}, /* Bounding rectangle */ 
documentProc, /* documentProc etc... */ 
Visible, /* Visible or Invisible */ 
goAway, /* GoAway or NoGoAway */ 
0, /* Reference value RefCon */ 
"Status Report" /* Title */ 


}; 


This data definition declares a resource of type 'WIND', using whatever type 
declaration was previously specified for 'WIND'. The resource ID is 128; the resource 
name is “My window”. Because the resource name is represented by the Resource 
Manager as a pstring, it should not contain more than 255 characters. The resource 
Name may contain any character including the null character ($00). The resource 


will be placed in the application heap when loaded, and it will be loaded when the 
resource file is opened. 


The first statement in the window type declaration declares a bounding rectangle for 
the window: 


rect; 


The rectangle is described by two points: the upper-left corner and the lower-right 
corner. The points of a rectangle are separated by commas as follows: 


(top, left, bottom, right} 
An example of data for these coordinates is 


{40, 80,120,300} 
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Symbolic names: Symbolic names may be associated with particular values of a 
numeric type. Notice that a symbolic name is given for the data in the second, third, 
and fourth fields of the window declaration. For example, 


integer documentProc=0, dBoxProc=1, plainDBox=2, 
altDBoxProc=3, noGrowDocProc=4, 
zoomProc=8, rDocProc=16; /* windowType */ 


This statement specifies a signed 16-bit integer field with symbolic names associated 
with the values 0 to 4 and 16. The values 0 through 4 need not be indicated in this 

case; if no values are given, symbolic names are automatically given values starting at 
zero, as explained previously. 


In the sample window declaration, we gave the values true (1) and false () to 
two different byte variables. For clarity, we used those symbolic names in the 
window’s resource data; that is, 


visible, 
goAway, 


instead of their equivalents 


TRUE, 
TRUE, 
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Preprocessor directives 


Preprocessor directives substitute macro definitions and include files, and provide 
if-then-else processing, before other Rez processing takes place. 


The syntax of the preprocessor is very similar to that of the C-language preprocessor. 
Each of the preprocessor statements must be expressed on a single line, beginning 
on a new line and terminated by a return character. Identifiers (used in macro 
names) may be letters (A-Z, a-z), digits (0-9), or the underscore character ( _ ). 
Identifiers may not start with a digit. Identifiers are not case sensitive. An identifier 
may be any length. 


Variable definitions 


The #define and #undef directives let you assign values to identifiers: 


#define macro data 
#undef macro 


The #define directive causes any occurrence of the identifier macro to be replaced 
with the text data. You can extend a macro over several lines by ending the line with 
the backslash character (\), which functions as the Rez escape character. For 
example, 


#fdefine poem "I wander \ 
thro\' each \ 
charter\'d street" 


(Quotation marks within strings must also be escaped.) 


#undef removes the previously defined identifier macro. Macro definitions can 
also be removed with the -undef option on the Rez command line. 


The following predefined macros are provided: 
Variable Value 


true ak 
false 0 


Include directives 

The #include directive reads a text file: 

finclude (file 

Include the text file file. The maximum nesting is to 10 levels. 
For example, 

#include $$Shell("MPW") "MyProject :MyTypes.r" 


Note that the #include preprocessor directive (which includes a file) is different 
from the previously described include statement, which copies resources from 
another file. 
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If-Then-Else processing 
These directives provide conditional processing: 


#if expression 

{ #elif expression ] 
[ #else ] 

#fendif 


“* Note: Expression is defined later in this chapter; with the #if and #elif 
directives, expression may also include this expression: 


defined identifier or defined '( identifier‘! 
The following may also be used in place of #if: 


#ifdef macro 
#ifndef macro 


For example, 


#define Thai 


Resource 'STR ' (199) { 

#ifdef English 
“Hello” 

#felif defined (French) 
"Bonjour" 

#elif defined (Thai) 
“Sawati" 

#elif defined (Japanese) 
"Konnichiwa" 

#endif 


}3 
Print directive 


The #printf directive is provided to aid in debugging resource description files: 
#printf£(formatString, arguments...) 


The format of the #print£ statement is exactly the same as the printf statement in 
the C language, with one exception: There can be no more than 20 arguments. This is 
the same restriction that applies to the $$Format function. The #printf directive 
writes its output to diagnostic output. Note that the #printf directive does not end 
with a semicolon. 


For Example,: 


#define Tuesday 3 

#ifdef Monday 

#printf ("The day is Monday, day #%d\n", Monday) 
#elif defined (Tuesday) 

#printf("The day is Tuesday, day #%d\n", Tuesday) 
felif defined (Wednesday) 

#printf ("The day is Wednesday, day #%d\n", Wednesday) 
#elif defined (Thursday) 

printf ("The day is Thursday, day #%d\n", Thursday) 
telse 

#printf("DON'T KNOW WHAT DAY IT IS!\n") 

#fendif 

The above file will generate this text: 


The day is Thursday, day #3 
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Resource description syntax 


This section describes the details of the resource description syntax. For a complete 
summary definition, see Appendix D. 


Numbers and literals 


All arithmetic is performed as 32-bit signed arithmetic. The basic constants are 


Decimal mmm... Signed decimal constant between 4294967295 and 
—2147483648. 

Hex OXAAA... Signed hexadecimal constant between OX7FFFFFFF and 
0X80000000. 

Shhh... Alternate form for hexadecimal constants. 

Octal 0000... Signed octal constant between 017777777777 and 
020000000000. 

Binary OBDbb... Signed binary constant between 


0B11111111111111111111111111111111 and 
0B10000000000000000000000000000000. 


Literal 'aaaa' A literal can contain one to four characters. Characters are 
printable ASCII characters or escape characters. 
If there are fewer than four characters in the literal, 
then the characters to the left (high bits) are assumed to be 
$00. Characters that are not in the printable character set, 
and are not the characters \' and \\ (which have special 
meanings), can be escaped according to the character 
escape rules. (See “Strings” later in this section.) 


Literals and numbers are treated in the same way by the Resource Compiler. A literal 
is a value within single quotation marks; for instance, 'A' is a number with the value 
65; on the other hand, "A" is the character A expressed as a string. Both are 
represented in memory by the bitstring 01000001. (Note, however, that "A" is not a 
valid number and 'A' is not a valid string.) The following numeric expressions are 
all equivalent: 

1B! 

66 

TA'+1 


Literals are padded with nulls on the left side so that the literal 'ABC' is stored as 
shown in Figure 8-3. 


; — ; jo] a fe fe 


Figure 8-3 
Padding of literals 
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Expressions 


An expression can consist of simply a number or literal. Expressions can also 
include numeric variables and the system functions: 


$Scountof ‘(’ array-name'‘)’ 


$$ID expressions can include the expression operators listed in Table 8-1. Table 8-1 
lists the operators in order of precedence with highest precedence first—groupings. 
indicate equal precedence. Evaluation is always left to right when the priority is the 
same. Variables are defined following the table. 


Table 8-1 
Resource description expression operators 
Operator Meaning 
1. ( expr) Parentheses can be used in the normal manner to force 
precedence in expression calculation. 
2. -expr Arithmetic (two’s complement) negation of expr. 
~expr Bitwise (one’s complement) negation of expr. 
! expr Logical negation of expr. 
3. exprl * expr2 Multiplication. 
exprl / expr2 Division. 
expr1 % expr2 Remainder from dividing expr1 by-expr2. 
4. expr1 + expr2 Addition. 
exprl - expr2 Subtraction. 
5. exprl << expr2 Shift left—shift expri left by expr2 bits. 
expr1 >> expr2 = Shift right—shift expri right by expr2 bits. 
6. exprl > expr2 Greater than. 
exprl >= expr2 Greater than or equal to. 
expr1 < expr2 Less than. 
exprl <= expr2 Less than or equal to. 
7. exprl == expr2 Equal. 
expr1 != expr2 Not equal. 
8. exprl & expr2 Bitwise AND. 
9. exprl * expr2 Bitwise XOR. 
10. exprl | expr2 Bitwise OR. 
11. exprl && expr2 Logical AND. 
12. exprl | | expr2 Logical OR. 
The logical operators !, >, >=, <, <=, ==, !=, &&, || evaluate to 1 (true) or 0 (false). 
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Variables 


There are some Resource Compiler variables that contain commonly used values. 
All Resource Compiler variables start with $$ followed by an alphanumeric 
identifier. 


The following variables have string values (typical values are given in parentheses): 
$$Version Version number of the Resource Compiler. ("V2.0") 


$$Date Current date. Useful for putting timestamps into the 
resource file. The format is generated through the ROM 
call [UDateString. (Thursday, May 20, 1987") 


$$Time Current time. Useful for timestamping the resource file. 
The format is generated through the ROM call 
TUTimeString. ("7:50:54 AM") 


$$Shell("stringExpr") | Current value of the exported Shell variable {stringExpr 
}. Note that the curly braces must be omitted, and the 
double quotes must be present. 


$$Resource ("/ilename", 'type', ID | “resourceName" ) 
Reads the resource 'type' with the ID Dor the name 
"resourceName" from the resource file "/ilename", 
and returns a string. 


$$Format ("/ormatString", arguments) : 
Works just like the #print£ directive except that 
$$Format returns a string rather than printing to 
standard output. (See “Print Directive” earlier in this 
chapter.) 


The following string variables can be used in the AS resource description to modify 
the resource information in include statements: 


$SType Type of resource from include file. 
$S$ID ID of resource from include file. 
$SName Name of resource from include file. 


SSAttributes Attributes of resource from include file. 


For example, to include all DRVR resources from one file and keep the same 
information, but also set the SYSHEAP attribute: 


INCLUDE "“file"™ 'DRVR' (0:40) AS 
‘'DRVR (SSID, S$S$Name, S$SAttributes | 64) ; 


The $$Type, S$$ID, $SName,and $$Attributes variables are also set and legal 
within a normal resource statement. At any other time the values of these variables 
are undefined. 


The following variables have numeric values: 


$$Hour Current hour. Range 0-23. 
$$Minute Current minute. Range 0-59. 
$$Second Current second. Range 0-59. 
$$Year Current year. 

$$Month Current month. Range 1-12. 
$$Day Current day. Range 1-31. 


$$Weekday Current day of the week. Range 1-7 (that is, Sunday—Saturday). 
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Strings 
There are two basic types of strings: 


Text string "a..." The string can contain any printable character except ‘"’ 
and ‘\’. These and other characters can be created 
through escape sequences. (See Table 8-2.) The string "" 
is a valid string of length 0. 


Hex string $"hh..." Spaces and tabs inside a hexadecimal string are ignored. 
There must be an even number of hexadecimal digits. 
The string $"" is a valid hexadecimal string of length 0. 


Any two strings (hexadecimal or text) will be concatenated if they are placed next to 
each other with only white space in between. (In this case, returns and comments are 
considered white space.) 


Figure 8-4 shows a Pascal string declared as 
pstring (10]; 
whose data definition is 


"Hello" 


Figure 8-4 
Internal representation of a Pascal string 


In the input file, string data is surrounded by double quotation marks (""). You can 
continue a string on the next line. A separating token (for example, a comma) or 
brace signifies the end of the string data. A side effect of string continuation is that a 
sequence of two quotation marks (""") is simply ignored. For example, 


"Hello Ww “out wt 
"there." 


is the same string as 


"Hello out there."; 


To place a quotation mark in a string, precede the quotation mark with a backslash 


CAD: 


8-24 Chapter 8: Resource Compiler and Decompiler 


Escape characters 


The backslash character (\) is provided as an escape character to allow you to insert 
nonprintable characters in a string. For example, to include a return character in a 
string, use the escape sequence 


\r 


Valid escape sequences are given in Table 8-2. 


Table 8-2 

Resource Compiler escape sequences 

Escape Hex Printable 
sequence Name value equivalent 
Xt Tab $09 None 
\b Backspace $08 None 
\xr Return $0D None 
\n Newline® $0D None 
\f Form feed SOC None 
\v Vertical tab $0B None 
7 Rubout $7F None 
\\ Backslash $5G \ 

< Single quote $3A 

Vv Double quote $22 : 


“On the Macintosh, newline is identical to return. 


You can also use octal, hexadecimal, decimal, and binary escape sequences to 
specify characters that do not have predefined escape equivalents. The forms are as 
follows: 


Number 
Base Form of digits Example 
2 \0Bbbbbbbbb 8 \0B01000001 
8 \ ooo 3 \101 
10 \0Dddd S \OD065 
16 \OXhA 2 \OX41 
16 \Shh 2 \$41 


Some examples are 


\077 /* 3 octal digits */ 

\OxFF /* ‘Ox’ plus 2 hex digits */ 
\SFI\SF2\SF3  /* ‘S$’ plus 2 hex digits 
\O0d099 /* ‘Od’ plus 3 decimal digits */ 


*° Note toc programmers: An octal escape code consists of exactly three digits. For 
instance, to place an octal escape code with a value of 7 in the middle of an 
alphabetic string, write AB\OO7CD, not AB\7CD. 


You can use the DeRez command line option -e to print characters that would 
otherwise be escaped (characters preceded by a backslash, for example). Normally, 
only characters with values between $20 and $D8 are printed as Macintosh 
characters. With this option, however, all characters (except null, newline, tab, 
backspace, formfeed, vertical tab, and rubout) will be printed as characters, not as 
escape sequences. 


a or 
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Overview of the build process 


This chapter describes the mechanics of building a program—the steps involved are 
nearly the same for applications, MPW tools, desk accessories, and drivers. All 
programmers should read the opening sections of this chapter, which explain the 
entire build process for an application, the standard case. Later sections explain 
what's different about building an MPW tool, desk accessory, or driver. 


Those new to MPW should first read “Building a Program: An Introduction” in 
Chapter 2. This brief introduction takes you through the steps of using the Directory 
and Build menus to build a program. 


Building a program consists of the following steps: 


1. Create source files and compile them. Source files are compiled or assembled to 
produce object files. (For information on writing programs in Pascal, C, or 
assembly language, and including the proper interface or include files, see the 
appropriate MPW language manual.) 


2. Create additional resources with ResEdit or Rez. If your program requires any 
additional resources (other than code resources), you can create them by using 
the resource editor (ResEdit) or Resource Compiler (Rez). See Chapters 7 and 8 
for detailed information. 


3. Create the final executable file with Link. The object files are linked together, 
along with any needed library routines, into either a new resource file or an 
existing one (replacing the 'CODE', 'DRVR', or other executable resources). 


** Note: For building a desk accessory or driver in Pascal or C, an additional step is 
required—run Rez to create the final 'DRVR' resource. For details, see “Building 
a Desk Accessory or Driver,” later in this chapter. 
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Figure 9-1 illustrates the complete process. 


Shell editor 


Source 
files 


=.0,3,.),5.C 
‘TEXT’ 


Compiler or Assembler 
ResEdit, or Rez 


Libraries 
3,0 
‘OBJ' 


Resource 


file 
=..STC 


Executable 
code resources 
‘APPL','MPST',... 


Figure 9-] 
Building a program 
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For example, the following series of commands compile, “Rez,” and link the sample 
Pascal application Sample.p: 


Pascal Sample.p 

Rez Sample.r -o Sample 

Link Sample.p.o a 
“{Libraries}"Interface.o da 
"(Libraries}"Runtime.o da 
"(PLibraries}"Paslib.o @ 
-o Sample 


This process is usually automated by using the Make tool. (See the sample makefiles 
in the Examples folders, and “Using Make” in Chapter 10.) 


“* Note: If you build an application with customized icons for documents (that is, a 
'BNDL' resource for bundling 'ICN#' and 'FREF' resources), then you need to use 
SetFile to set your application’s bundle bit: 


SetFile -a B MyApp 


See the Finder Interface chapter of Inside Macintosh for information. 


The structure of a Macintosh application 


Macintosh files have two forks: a resource fork and a data fork. The resource fork 
contains a number of resources. The data fork may contain anything the application 
puts there. On the Macintosh, a program is a file whose resource fork contains code 
resources (‘'CODE' or other executable resources), and in most cases additional 
resources containing strings, dialogs, menus, and the like. The code resources for 
applications and tools must contain a main program (an execution starting point). 
Desk accessories and drivers, by contrast, don’t require a main program, but 
contain collections of routines that are called individually when the desk accessory or 
driver is used. 


The simplest possible application has two resources in the resource fork and nothing 
in the data fork. The first resource is a 'CODE' resource with ID = 0. (The Linker 
creates this resource, which contains the jump table and information about the 
application’s use of parameter and global space.) The second resource is a 'CODE' 
resource with ID = 1, which contains the application’s code segment. For more 
information, see the Segment Loader chapter of Inside Macintosh. 
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Linking 


This section describes how to link an application, MPW tool, desk accessory, or 
driver. 


“« Note: For more information about Linker functions, see “More About Linking” in 
Chapter 10. The Link command itself is described in Part II. The MPW object file 
format is described in Appendix F. 


The Linker links object files into an application, MPW tool, desk accessory, driver, 
or other executable resource. The Linker’s output is an executable object file. The 
Linker links together the compiled or assembled object files, along with any needed 
library routines, into either an existing resource file (replacing the 'CODE', 'DRVR', 
or other executable resources) or a new one (Figure 9-2). 


Object 
files Libraries 
2.0 sie 
‘OB ‘OBJ' 


Code 
resources 
‘APPL’, 
‘MPST', 
or ‘DRVR' 


Figure 9-2 
Linking 


The Linker resolves all symbolic references, and also controls final program 
segmentation. A related tool, Lib, provides facilities for modifying and combining 
object files Cibraries). 


The Linker’s default action is to link an application (type APPL, creator "????"), 
placing the output segments into 'CODE' resources. You can set a file’s type and 
creator with Link’s -t and -c options. (See “File Types and Creators” below.) 
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What fo link with 


Applications, tools, and desk accessories should be linked with the libraries listed in 

Table 9-1. It’s wise to link new programs with all of the libraries that might be needed. 
If unnecessary files are specified, the Linker will display warnings indicating that they 

can be removed from your build instructions. 


Table 9-1 
Files to link with 


Inside Macintosh interfaces 
{Libraries}Interface.o 


Runtime support 
Link with one of the following: 


{Libraries}Runtime.o If no part of the program is written in C 
{CLibraries}CRuntime.o If any part of the program is written in C 


Pascal libraries 
{PLibraries}PasLib.o Pascal language library 
{PLibraries}SANELib.o SANE numerics library 


C libraries 

{CLibraries}CInterface.o | Macintosh interface for C 
{CLibraries}CSANELib.o SANE numerics library 
{CLibraries}Math.o Math functions 
{CLibraries}StdCLib.o Standard C Library 


Specialized libraries 
You may also call routines in the following libraries: 


{Libraries}ObjLib.o Object-oriented programming (Pascal and Assembler) 
{Libraries}ToolLibs.o Routines for MPW tools 


Desk accessories 
{Libraries}sDRVRRuntime.o Driver runtime library 


For details about linking tools and desk accessories, refer to “Linking a Tool” and 
“Linking a Desk Accessory or Driver” later in this chapter. 


Linking multilingual programs 


When you link programs that use libraries from more than one language, the Linker 
may detect several duplicate entry points. Normally it doesn’t matter which of the 
duplicate copies of a particular routine get linked with your program. (You can use 
the Linker’s -w option to suppress the duplicate definitions warnings.) 


However, programs written partly in C and partly in assembly language or Pascal 
require special precautions. When you link C code with other languages, link with the 
file CRuntime.o and not with Runtime.o. If execution is expected to begin with the C 
function main (), no special action is necessary. However, if your main program is 
written in assembly language or Pascal, but part of your program is written in C, the 
object file containing your main program must appear before CRuntime.o in the list 
of object files passed to the Linker. 
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File types and creators 


When you execute a command, the Shell determines how to mun it based on.its file 
type. Files of type APPL are considered applications and are run as if launched from 
the Finder. Files of type MPST are considered MPW tools and are run within the Shell 
environment. Files of type TEXT are taken to be scripts and are interpreted by the 
Shell. An attempt to run a file of any other type produces an error message. Table 9-2 
summarizes file types and creators. 


Table 9-2 

Fila types and creators 

Type of program Type Creator 
Application APPL any 
MPW tool MPST 'MPS '! 
Desk accessory DFILD MOV 
Script TEXT any 


¢¢ Note: Each application has its own unique creator (or signature)—see the 
Finder Interface chapter of Inside Macintosh. For example, creating a file with 
the type DFIL and creator DMOYV, tells the Font/DA Mover that this file contains 
desk accessories. 


You can set a file’s type and creator with the -t and -c options to Link, Rez, or SetFile. 


Building a desk accessory or driver 


A desk accessory is a 'DRVR' resource whose resource name begins with a null 
character (S00), and that resides in the System file. To make it convenient to write a 
desk accessory or driver in Pascal or C, MPW provides the following: 


Q The library DRVRRuntime.o, which contains the glue for the driver routines open, 
prime, status, control, and close. 


CQ The resource type 'DRVW', declared in :RIncludes:MPWTypes.r. The 'DRVW' 
resource is a special case of a 'DRVR' resource, and contains constants that point 
to the addresses of the driver routines in DRVRRuntime.o. 


For information on using the 'DRVW' resource and DRVRRuntime routines to write a 
desk accessory, see Chapter 15. The remainder of this section describes how to put 
together a desk accessory and install it. 


Putting together a desk accessory or driver requires two steps: 


1. Link your driver code with the DRVRRuntime library and with any other libraries 
you need. The object code is linked into a code resouce of type 'DRVW', an 
intermediate form of the standard 'DRVR' resource. 


2. Use the Resource Compiler, Rez, to create the final driver file. That is, compile 
the linked 'DRVW' resource into a standard 'DRVR' resource, using the 'DRVW' 
type declared in :RIncludes:MPWTypes.r, together with any other resources your 
desk accessory may require. 


You then install your desk accessory in the System file by using the Font/DA Mover. 
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Figure 9-3 illustrates the process of building a desk accessory or other driver. 


Compiled DRVR- 
code library libraries 
(type ‘OBJ’) 


MPW- 
‘DRVW' Types.r Additional 
resource (for ‘DRVW' resources 
declaration) 


Resource Compiler 
(Rez) 


Driver file 
CORVR' 


resource; 
type 'DFIL') 


Figure 9-3 
Building a desk accessory with DRVRRuntime 


** Note: Of course, it’s still possible to create a desk accessory directly in assembly 
language, without using DRVRRuntime. 
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Linking a desk accessory or driver 


These things must be done to link a driver or desk accessory: 


O The Linker’s -rt option must be specified. The -rt option indicates the link of a 
desk accessory or driver and sets the resource type and ID. (The default, if no -rt 
option is specified, is to output 'CODE' resources beginning with resource ID 0.) 


Q When you link a desk accessory or driver, the code must be in a single segment 
(that is, no jump table is constructed). You can map code from several segments 
into a single segment with the -sg or -sn options. 


O Desk accessories written in Pascal or C must be linked with DRVRRuntime.o, which 
should appear first in the list of object files. 


For example, the following command links the sample desk accessory file 
Memory.c.o, placing the output in the file Memory. (This output is the intermediate 
"DRVW' resource, which must be converted into a 'DRVR' resource as explained in 
the next section.) 


Link -w @ 
-rt DRVW=0 da 
-sn Main=Memory @ 
"{Libraries}"DRVRRuntime.o # must appear first @d 
Memory.c.o @ 
"{CLibraries}"CRuntime.o a 
"(CLibraries}"CInterface.o @ 
-o Memory.DRVW 


This command has these results: 
Q The -rt option sets the output resource type to 'DRVW’' and the resource ID to 0. 


Note: This ID must match the ID specified in the $$resource statement in the 
Rez input file. Note also that any additional resources “owned” by the desk 
accessory must observe a special numbering convention, as described in the 
Resource Manager chapter of Inside Macintosh. 


OQ The -sn option combines the segment Main into the segment Memory. 


Q The specified files are linked. The DRVRRuntime.o library must be the first object 
file in the link list. This ordering ensures that the main entry point in CRuntime.o 
will be overridden by the DRVRRuntime.o entry point. (A Linker warning will call 
attention to this requirement.) The main entry point in CRuntime.o cannot be 
used for desk accessories. 


Desk accessories must not call routines that use global variables, and therefore are 
less likely to need routines from the Pascal, C, and specialized libraries listed in 
Table 9-1. In a correct link, the Linker’s progress information will report “Size of 
global data area: 0,” and “No data initialization.” If global data is somehow 
allocated, the link will succeed, but the desk accessory will not run correctly. 
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The desk accessory resource file 


The last step in the construction of a desk accessory or driver is to put together the 
DRVR header with the linked code. The following example of a Resource Compiler 
(Rez) input file shows how this is done: 


#include "Types.r" 
#include "MPWTypes.r" 


type 'DRVR' as 'DRVW'; 
#define DriverID 12 /* The number is irrelevant */ 


resource 'DRVR' (DriverID, "\Ox00Memory", purgeable) { 


dontNeedLock, /* OK to float around, not saving ProcPtrs */ 
needTime, /* Yes, give us periodic Control calls */ 
dontNeedGoodbye, /* No special requirements */ 
noStatusEnable, 

ctlEnable, /* Desk accessories only do Control calls */ 
noWriteEnable, 

noReadEnable, 

5*60, /* Wake up every 5 seconds */ 

updateMask, /* This DA only handles update events */ 

0, /* This DA has no menu */ 

"Memory", /* This isn't used by the DA <«/ 


S$resource("Memory.DRVW", 'DRVW', 0) 
i 


The header information contains the details of the desk accessory’s event mask, 
menu ID, and so on. (See the Device Manager chapter of Inside Macintosh and the 
file MPWTypes.r for information about the format of a 'DRVR' resource.) The 
$$resource directive then appends the linked object code to the DRVR header 
where it belongs. 


If your desk accessory has any owned resources, such as 'STR#' or "WIND! resources, 
you can add them to your desk accessory’s Resource Compiler input. 


To build the desk accessory resource, use the Rez command to compile the resources 
you have specified, and set the file type and creator for a Font/DA Mover document: 


Rez -c DMOV -t DFIL Memory.r -o Memory 


The file type DFIL indicates a document file for the Font/DA Mover; the creator 
DMOV indicates a Font/DA Mover document (suitcase icon). 


To install a desk accessory, use the Font/DA Mover to place the desk accessory in the 
System file. You can do this from MPW as follows: 


“Font/DA Mover" Memory 


After exiting the Font/DA Mover, you can execute the desk accessory by selecting its 
name from the Apple menu. 
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Modifying the Build menu and makefiles 


The Directory and Build menus are implemented as AddMenu commands and 
Scripts. This lets you customize these menus to serve your own specific needs. In 
addition, the makefiles created by using the Create Build Commands menu option 
(script CreateMake) can be modified as your scripts grow in complexity. See 
Chapter 3 for a description of the Directory and Build menus. 


Variables 


The Shell variable {Program} is used to remember the name of the most recently 
built program. It is set by the Create Build Commands...menu item and by each of 
the Build... menu items. {Program} is used as the default program name for the Build 
menu items. 


Scripts 


The following scripts implement the Directory and Build menus. A © following the 
name of the script indicates that the script supports a Commando interface. Size 
estimates are also provided. These scripts are located in the Scripts: folder. Each is 
documented in detail in Part II. 


DirectoryMenu 2K Create the Directory menu 

SetDirectory © 2K Set the current directory 

BuildMenu 2K Create the Build menu 

CreateMake © 4K Create a program makefile 

BuildProgram 2K Build the selected program show build commands 
BuildCommands 

Files 

Items in the Directory and Build menus may create the following files: 
<Program>.make Makefile containing build commands for program 
<Program>.makeout Build instructions for current build 
{MPW}MPW.Errors Diagnostic output from commands run from menus 
UserStartup 


The Directory and Build menus are installed by scripts from the UserStartup file. The 
commands listed below should be in UserStartup. In addition to creating the 
Directory and Build menus, they create the aliases needed to support the Directory 
menu. 


DirectoryMenu ° (Files -d "{MPW}"sExamples=) > Dev:Null- “Directory 
BuildMenu 


The parameters to DirectoryMenu become the initial list of directories in the 
Directory menu. You can replace or augment the Examples directories with your 
favorite list of directories. 
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Modifying the makefiles 


As the complexity of your program increases, you can modify the makefile created 
by the Create Build Commands menu item. You might add new dependencies, 
specify Compiler and Linker options, and so on. The Build menu item will continue 
to build the program, using the modified instructions. 


include dependencies 


You may want to modify a makefile created by the Create Build Commands menu 
item, in order to overcome the limitations of the CreateMake script. Makefiles 
created by CreateMake do not include dependencies on include files or Pascal 
USES files. If you plan to change the Include or Uses files, consider modifying the 
makefile to express these dependencies. 


For example, assuming that the C source file Count.c includes the header file 
Utilities.h, add the following dependency rule to the file Count.make: 


Count.c.o f Utilities.h 


No build rules are required; just add the dependency rule. Several include or USES 
files can be listed in the same dependency rule, or separate rules can be used for 
each dependency. Don’t forget to specify the directory for files located in another 
directory. 


Library object files 


Makefiles created by CreateMake link your program with the selected libraries listed 
on the CreateMake command page in Part Il. The libraries are selected according to 
the language(s) in which your program is written and according to the program type 
(application, tool, desk accessory). 


If your program calls routines in a library that is not automatically included in the 
build commands, then modify the makefile to add that library. The library’s name 
should be added in two places: in the dependency rule immediately before the Link 
command (if you expect to modify the library), and in the list of libraries in the Link 
command itself. 


If you consistently need to add the same library to your makefiles, you can modify 
the CreateMake script to include it automatically in the dependency and build rules. 
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Building an MPW tool 


In addition to traditional Macintosh applications, the Shell provides an 
environment for a type of program called an MPW tooL Tools are similar to desk 
accessories in many aspects of their behavior. When a tool is run from the Shell, it 
does not replace the Shell nor erase the screen, but instead runs within the Shell 
environment and has access to the facilities provided by the Shell. The Assembler, 
the Compilers, Link, Make, and so on, are all tools in the MPW system. 


Chapter 13 is a full exposition on writing MPW tools. For a description of the facilities 
available to an MPW tool, see Appendix F. 


Linking a tool 


Linking an MPW tool is the same as linking an application, except that the file type 
must be set to MPST and the creator to 'MPS ' (MPSspace): 


Link =t. MPST =e. "MPS -o.:, 


Sample tools are provided in the Examples folders for each of the MPW languages— 
refer to the sample makefiles for examples of the commands used to build a tool. 
Note that the sample tools are linked with the files Stubs.a.o or Stubs.c.o. These files 
contain dummy library routines used to override standard library routines that aren’t 
used by MPW tools, thus reducing the tools’ code size. 


“+ Note: As a matter of convenience, tools are usually kept in the ({MPW}Tools 
folder. This allows you to invoke the tool by using its simple name instead of its 
full pathname. {MPW}Tools is one of the directories that the Shell automatically 
searches when a command name is given with a partial pathname. (The Shell 
variable {Commands} contains a comma-separated list of directories to be 
searched; you can easily modify it to include additional directories.) 
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Chapter 10 


Advanced 
Programming 
Tools 


Using Make 


The Make tool enables you to keep track of all of the components of a program and 
their relationships to each other—then, when one component of a program is 
modified or updated, Make lets you automatically update all other parts of the 
program that depend upon it. These updates may be such things as compiles, 
assemblies, links, and resource compiles. 


Make reads a makefile that describes the dependencies of the various components 
of a program, and outputs commands on the basis of those dependencies. This 
section describes how to write a makefile and use Make. (The Make command and 
command-line options are described in Part II.) 


Format of a makefile 


A makefile is a text file that describes dependency information for one or more target 
files. A target file is a file to be rebuilt; it depends on one or more prerequisite 
files that must exist or be up-to-date before the target can be rebuilt. For example, 
an application depends on its source file or files, a number of library files, and 
resource files. If any of a target’s prerequisite files are newer than the target, then the 
target needs to be rebuilt. 


The dependency relationship of target prerequisites can be recursive, that is, a 
target’s prerequisites may themselves be targets with their own prerequisites, and so 
on. A top-level target Cone that is not a prerequisite of any other target) is called a 
root. A makefile may have one or more roots. 


A makefile can include dependency rules, variable definitions, and comments. 
Table 10-1 summarizes the syntax of a makefile, and the sections following the table 
go into more detail. 


Table 10-1 
Makefile summary 
targetFile... f [ prerequisiteFile... | Dependency rule, with or without build commands. (¢ is 
{ ShellCommanda.... | Option-F on the keyboard.) This rule means that targetFile 


depends upon prerequisiteFile. If any of the prerequisites are 
newer than the target, the subsequent Shell commands are 
output so that the target can be made up-to-date with respect 
to its prerequisites. 


Important: Build commands must begin with a space or tab. 


targetFile... ff | prerequisiteFile... | Dependency rule, requiring its own set of build commands 
ShellCommanas... 

Asuffixl f .suffix Default rule (specifies suffix dependencies) 
ShellCommana.... 


targetDirectory: ... f searchDirectory: ... 
Directory dependency rule (used with default rules) 


variableName = stringValue Variable definition 

# comment Comment 

{name} Variable reference 

ME gg ip Mages. Quotes (as in the Shell) 
dReturn © Line continuation character 
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“* Note: Makefile physical input lines may not exceed 255 characters. Logical input 
lines (made up of one or more physical input lines continued with the 
continuation character) may be of arbitrary length. 


A makefile for the sample Pascal application (Sample) is shown below: 
### Variable Definitions ### 


Libs = "(Libraries}"Interface.o 0 
"(Libraries}"Runtime.o ad 
"“(PLibraries})"Paslib.o 


### Dependency Rules ### 


Sample ff Sample.r # Sample depends on Sample.r 
Rez Sample.r -o Sample 
Sample ff Sample.p.o # Sample depends on Sample.p.o ad 
Sample.r # and Sample.r 
Link Sample.p.o @ 
{Libs} @ 
-o Sample 
Sample.p.o f Sample.p 


Pascal Sample.p 


Sample makefiles are contained in the Examples folders for each of the MPW 
languages (introduced in Chapter 2). 


Dependency rules 


A dependency rule specifies the prerequisite files of a given target file, together 
with a list of the commands needed for building the target file. These commands will 
be written to standard output if any one of the prerequisite files is newer than the 
target file or if the target doesn’t exist. The general form of a dependency mule is 


targetFile... f [ prerequisiteFile... | 
[ ShellCommand.... | 


The first line is called the dependency line. It consists of one or more target file 
names, followed by the f (Option-F) character (meaning “is a function of”), 
followed by a list of prerequisite files separated by blanks or tabs. Make looks at the 
modification dates of the prerequisite files (and their prerequisites, if any) and 
decides whether the target needs to be rebuilt. 


Because a target’s prerequisites may themselves be targets with their own 
prerequisites, the investigation of prerequisites is recursive and “bottom up.” Thus, 
commands to rebuild lower-level targets are issued, if necessary, before the 
dependency rule determines whether higher-level targets need to be rebuilt. 


All subsequent lines that begin with a space or tab are build command lines. These 
are Shell commands that will be output if the target needs updating. (When Make 
writes these command lines to standard output, the initial space or tab is omitted.) If 
the dependency rule omits the build commands, then the rule expresses only the 
target’s dependencies. The build lines for the target are assumed to be supplied by 
another rule. 
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For example, 


Sample.p.o f Sample.p 
Pascal Sample.p 


The first line in the example is a dependency rule for the Pascal object file 
Sample.p.o. This rule states that Sample.p.o depends on the source file Sample.p. 


The second line is the associated build command line. If Sample.p is newer than 
Sample.p.o, or if Sample.p.o doesn’t exist, the command Pascal Sample.p is 
written to standard output. 


More than one target file name can appear on the left-hand side of an “f rule.” Each 
target file on the left-hand side depends on all of the files listed on the right-hand 
side (and has the same build commands, if specified). If more than one target file is 
specified, it’s exactly as if a separate dependency rule had been given for each target. 
The built-in Make variable {Targ} has the value of the current target. 


You can also state multiple dependency lines for a single target—multiple 
dependencies mean that the target depends on all of the prerequisite names that 
appear on all of the lines. If no build commands are specified for a dependency line, 
the build commands are taken from the target’s other dependency rules, or default 
tules, if present. 


“* Note: With the standard “single-f” form of the dependency rule, only one 
sequence of build commands may be specified for any given target. Thus, one 
dependency rule specifies a target’s build commands, and additional rules 
simply specify additional dependencies. 


Double-f dependency rules 


Double-f dependency rules are slightly different from the standard single-f rules. 
Syntactically, a double-f dependency entry is the same as a single-f entry, except 
that ff is used in place of f. The difference in use is that more than one double-f 
tule is expressed for an individual target and that each double-f rule requires its own 
set of build commands. For example, 


TargetFile ff A B D 
build commands-1 

TargetFile ff Cc D 
build commands-2 


If the target is out-of-date with respect to one or more dependency sets, each of the 
corresponding sets of build commands will be output (in the order they appear in the 
makefile). That is, if TargetFile is out-of-date with respect to both A and C, then both 
sets of build commands are output (In single-f rules, only one set of build 
commands can be specified for any one target.) 


If TargetFile is out-of-date with respect only to B, then only the first set of build 
commands is output. If TargetFile is out-of-date with respect to D, then both sets of 
build commands are output, because D appears in the dependency sets for both. In 
other words, the same file can appear as a prerequisite in more than one double-f 
dependency set. 


Double-f rules are useful for separately building code and resources, as shown in the 


makefile for Sample. (For more examples, see the sample makefile at the end of this 
section.) 


The build commands may be left off a double-/ rule if they are to be supplied by 
default rules. 
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Default rules 


Default rules express dependencies between pairs of files whose names are the same 
but whose suffixes differ. They have the following form: 


Isuffixl) f .suffix2 
ShellCommandas... 


(Note that the period must be present for a default rule to be recognized. The period 
is taken as part of the suffix.) 


The power of default rules is that many specific dependencies and build commands 
can be expressed by a single rule, thereby eliminating the need to specify many 
similar dependency rules. Make has built-in default rules for assemblies and for C 
and Pascal compiles. You need to specify only the dependencies not covered by 
default rules. 


Default rules are applied only when no build commands have been given for a 
particular target. You can override the built-in default rules by placing your own 
versions of the default rules in the makefile. You can augment the default rules for a 
particular file by additional dependency rules, as long as these dependency rules do 
not include build commands. 


Default rules of the form 
fa suffix 


specify dependencies between files with any name and files with the same name 
followed by the given suffix. 


“» Note: Default rules of this form slow down Make processing, because the empty 
left-hand side of the rule causes it to match against all filenames. 


Built-in default rules: A compiled or assembled object file is dependent on its source 
file—this dependency is typically handled by the built-in default rules. 


Additional object file dependencies may result from other units that you use or refer 
to in your source file—these may be include files, C header files, or Pascal USES 
files. These additional dependencies can be expressed by dependency rules with no 
build line component, leaving the build lines and object-to-source dependency 
implied by the default rules. 


The data fork of the Make tool contains the following built-in default rules: 


.a.0 f .a 
{Asm} {AOptions} {DepDir}{Default}.a -o {TargDir})({(Default}.a.o 


s620 ff “ac 
{C} {(COptions} {DepDir}{Default}.c -o (TargDir}{Default}.c.o 


{pico f .p 
{Pascal} (POptions} ({DepDir}(Default}.p -o (TargDir}(Default}.p.o 


{Asm}, {Pascal}, and (C} are built-in Make variables. Their initial values are 


{Asm} Asm 
{Pascal} Pascal 
{C} G 
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{AOptions}, {POptions}, and {COptions} are initially null; you can customize the 
built-in default-rule build commands by defining these variables in your makefile. 
For instance, you might want to specify the location of your Pascal include files by 
adding a -i pathname option to the default rules by a variable definition of the form 


POption = -i pathname 


Or you may want to indicate the use of a different C compiler by changing the value of 
the {C} variable. 


You can redefine the {Asm}, {Pascal}, {C}, {AOptions}, {POptions}, and 
{COptions} variables. Variable definitions can be overridden in your makefile, on 
the command line (with Make’s -d option), or by an exported Shell variable. See 
“Variables in Makefiles” below for information. 


{Default} is another built-in variable; its value is the common part of the filenames 
matched by a default rule (defined dynamically when Make applies the default rule). 
The {Default} variable is what allows you to write a generic default rule without 
referring to a specific filename. Because its value is set dynamically by Make, its value 
cannot be overriden in your makefile. 


{DepDir} and {TargDir} are built-in Make variables that allow default rules to work 
with the target and prerequisite files in different (or the same) directories: 


{DepDir} The directory component of the prerequisite name 
{TargDir} The directory component of the target name 


“* Note: {(DepDir} and {TargDir} have values only when used in the build 
commands of default rules for which directory dependency rules were applied. 
In all other cases these variables evaluate to the null string so that they won’t 
interfere with the normal behavior of default rules. Directory dependency rules 
are explained in the section that follows. 


Directory dependency rules: Normally, default rules work only within a single 
directory, that is, the target and prerequisite files will.have the same directory 
component because the default rules change only the suffixes of the filenames. 
Directory dependency rules allow default rules to be applied across directories. Just 
as default rules imply changing a filename suffix between a target filename and a 
prerequisite filename, directory dependency rules imply changing the directory 
prefix of the filenames. Directory dependency rules have the form 


targetDirectory: .... f searchDirectory: ... 


Directory dependency rules are identified by dependency names that end in colons 
(that is, directory names). For example, 


ObjFiles: f SrcFiles: 


The above rule, together with the standard default rules, would mean, for example, 
that ObjFiles:zame.c.o depends upon SrcFiles:name.c. 


No build commands may be given for a directory dependency rule. More than one 
directory name may appear on either side of the rule. The current directory can be 
specified by a single colon (:) on either side of a directory dependency rule. 
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Directory dependency rules are applied only during the processing of default rules. If 
Make is applying a default rule and encounters a target name with a directory 
component, Make checks for a directory dependency rule for that directory. If one 
exists, Make tries prerequisite filenames with the directory prefixes given on the 
right-hand side of the rule. The names are tried in the order that they appear in the 
rule; thus more than one directory name on the right-hand side of a directory 
dependency rule constitutes a list of directories to search. 


“* Note: If default rules are meant to be applied from a directory A: to a directory 
B: and also within A: (that is, from A: to A:), then A: should appear on both the 
left and right sides of the directory dependency rule. For example, 


A: f As B: 


Variables in makefiles 


You can use exported Shell variables and built-in Make variables within makefiles. 
You can also define variables within a makefile or on the Make command line. 


Shell variables 


Make automatically defines exported Shell variables before it reads the makefile, so 
you can use Shell variables in dependency lines and build commands. 


If Make doesn’t recognize a variable reference in a build command line, the build 
line is left unchanged when it is output, so that it can be processed later by the Shell. 
(Unidentified variables in dependency lines are reported as errors.) 


Caution 


Exported Shell variables override Make variables with the same names. An 
attempt to redefine a Shell variable in the makefile resulfs in a warning message. 


Defining variables within a makefile 
Variable definitions are makefile entries of the form 
variableName = stringValue 


Subsequent appearances of {variableName will be replaced by stringValue. You 
can use line continuations to make a stringValue arbitrarily long. When a stringValue 
is continued across lines, any comments, blanks, or tabs at the end of the 
continuation line, and at the beginning of the line after the continuation, are 
replaced by a single blank. Thus variable values can conveniently contain lists of 
files. Note that variable values may contain references to other variables. 


One common use of variables is to provide parameters to the directory portion of 
filenames so that you can easily adapt a makefile to different directory setups. 


** Note: Make variables in build command lines are not expanded until Make 
generates the build commands—because command generation follows all 
dependency rule and variable definition processing, there’s no requirement that 
variable definitions appear before their references in build command lines. 


You can define a variable on the command line with Make’s -d option; this option 
overrides any definition of the variable within the makefile, thus allowing the 
definition in the makefile to function as a default. 
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Built-in Make variables 


The following built-in Make variables have values that are dynamically assigned (and 
that cannot be overridden) as Make generates the build commands: 


{Targ} The complete filename of the target on the left-hand side of the 
dependency rule whose build commands are being processed 


{NewerDeps} A list of the names of all of the target’s direct prerequisites that 
were newer than the target; that is, the files that caused the 
target to be out of date 


These built-in variables can be used only in build command lines, because they have 
no value when dependency lines are processed. They cannot be overridden. 


When default rules are applied, the following variables are also defined: 


{Default} The common part of the filenames matched by a default rule 
{TargDir} The directory component of the target name 
{DepDir} The directory component of the prerequisite name 


“* Note: When expanding the built-in variables {Targ}, {NewerDeps}, {TargDinr}, 
{DepDir}, and {Default} in build commands, Make automatically quotes their 
values, if necessary, because they will represent filenames or parts of filenames. 
Don’t quote them yourself. 


Quoting in makefiles 


The Make command supports several of the Shell’s quoting conventions. Quoted 
items can appear in dependency lines, variable definition lines, and build 
command lines. The following quoting characters are used: 


r) Quotes the subsequent character; that is, the d is removed and the 
subsequent character is taken to be a literal character (except when 
OReturn is used at the end of a line as a continuation character). 


Quotes the enclosed string. The single quotes are removed. 


Quotes the enclosed string, but (...} variable references are expanded, and 
the escape character 0 is processed. The double quotes are removed. 


Quotes are processed as follows: 


O In dependency lines and in the name part of variable definitions, quotes literalize 
the quoted characters (useful for file or variable names). 


O On the right-hand side of variable definitions, quoted items are passed through 
“as is,” so that the quoting will take effect when the variable is expanded. 


O In build command lines, quoted items are passed through as is, so that the quoting 
will take effect when the build commands are executed by the Shell. 


Line continuation character 


Like Shell commands, dependency and variable definition lines can be continued 
over more than one line with dReturn. dReturn causes the d, any blanks preceding 

the 0, the return, and any leading blanks on the next line to be replaced with a single 
space. Comments at the ends of such continued lines do not comment out the 
continuation character. 
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Comments in makefiles 


The number sign C#) indicates a comment. Everything from the # to the end of the 
line is ignored. Comments always end at the next return, even if the return is 
preceded by a 0. 


Comments may appear in dependency lines, variable definitions, and build 
command lines, or on lines by themselves. Comments in build command lines are 
passed through to standard output where they are processed as comments by the 
Shell. 


Executing Make’s output 


Make generates a set of commands, which must be executed separately to perform 
the actual updates. You can automatically execute Make’s command output by calling 
Make from a Shell script. The simplest form of such a script consists of the two 
commands 


Make {"Parameters"} > MakeOut. 
MakeOut 


The first command executes Make, using the parameters passed to the script. (See the 
description of the {"Parameters"} variable in Chapter 5 under “Variables.”) Output 
(that is, build commands) is redirected to the file MakeOut. The second line of the 
script executes MakeOut 


The order in which Make builds targets 


Make builds the top-level target and its prerequisite subtargets in a recursive “bottom 
up” fashion. The top-level target (or targets) may be specified on the Make 
command line. If no target is specified on the command line, the default top-level 
target is the first target appearing on the left side of a dependency rule in the 
makefile. 


The prerequisites of the top-level target (and subtargets) are investigated in a 
recursive “bottom up” order starting with the first prerequisite mentioned in the 
target’s prerequisite list. After the first prerequisite (and its own prerequisites) have 
been investigated, the target’s next prerequisite is investigated. The next prerequisite 
will be the next one mentioned in the current dependency rule or in the next 
dependency rule in the file that has the same left-side target. 


Thus the important orderings within a makefile are: the first target mentioned (the 
default top-level target) and the order of prerequisites for any given target. 
Otherwise, the order in which targets are mentioned is not important. 


Please note, however, that once a target has been investigated by Make it is not 
revisited even if it appears somewhere else in the top-level target’s prerequisite 
dependency hierarchy. In other words, while a file may appear as a prerequisite of a 
number of program components, Make will rebuild it only once (if necessary) when 
it is first encountered in the recursive “bottom up” traversal of the dependency 
hierarchy. 


Remember that a makefile may have one or more top-level targets (or roots), that is, 
it may describe how to build more than one object. (The -r option will identify all the 
roots.) Running Make will rebuild only the targets you specify on the command line, 

or the default target if none are specified. 
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Debugging makefiles 


When Make doesn’t seem to be doing what you expect, the next step is to debug your 
makefile. The following procedures are helpful in debugging makefiles: 


1. Use Make’s -v option to generate verbose diagnostic output. This output tells you 
which files don’t exist, which files are up-to-date, which files need rebuilding, and 
why they are out-of-date. It also points out which files don’t have build rules and, 
thus, are assumed to be artificial targets (targets that are abstract and not really 
built—see, for example, Note 8 in the Make example that follows this section). 


2. Use Make’s -s option to show the structure of your target’s dependency relations. 
This option displays the complete structure of dependencies, including those 
generated by default rules. A target (or subtarget) that doesn’t appear or that has 
no prerequisites may indicate a typographical error in the dependency line for 
that target (or in the line for one of the targets that depend on it). A target that 
appears at the wrong level in the dependency graph indicates an error in your 
dependency specification. 


3. Use the -u option to find unreachable targets. These may be parts of your target 
dependencies that did not get connected to the rest of the dependency hierarchy 
because of a bad or mistyped rule. 


Problems due to command generation before execution 


Make generates commands that must be separately executed to perform the actual 
updates. Because Make must determine what build commands to generate before any 
targets are actually built, the possibility of “phase errors” is introduced; that is, 
unexpected behavior may occur when generated commands alter the assumptions 
that Make used to determine whether targets were out of date. (You won't experience 
these problems unless you have build commands that do things such as deleting files 
that Make thinks are already up to date.) 


Problems with different specifications for the same file 


You'll experience problems with Make if you use different pathname specifications 
for the same file (that is, pathnames with different degrees of volume and directory 
qualification). Make uses the name strings exactly as encountered in dependency 
lines, so different name strings will result in different entries. (This is done for the 
sake of performance—no calls are made to the file system, except to inquire about 
the date of targets that are supposed to be built.) If there is more than one name 
specification for the same file, each name results in a different Make target, and the 
resulting dependency relations will be wrong. 


Problems with default rules 


An error message may appear saying that no rules were available to build something 
that should have been covered by a default rule. This situation may result from any 
one of the following problems: 


QO The default rule may not have matched against anything, and was thus not 
applied; for example, the default rule 


p.o f .p 


cannot be applied if the .p file does not exist either in the file system or in the 
makefile dependency specification. 
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OQ There may be a typographical error in the filename, so that the default rule could 
not be applied. You should be able to detect such errors by inspecting the output 
of Make’s -s and -v options. 


OQ There may be a typographical error in a default rule that was given in the makefile, 
in which case you may not see any dependencies generated by the rule when you 
use the -s option on the Make command line. 


An example 


This section lists the makefile used to build an experimental version of the Make tool 
itself (represented in this makefile by the MakeX target). A series of explanatory notes 
follows the listing. These notes describe in detail a number of the Make features that 
were used. 


FFHHt HHT THS TEER ETE EE Variables FFF Fees FEET EEE HS FETE 


ToolDir = {Boot}ToolUnits: See note © 

MakeUses = {ToolDir}MacInterfaces.p.o See note @ 
{ToolDir}MemMgr.p.o 
{ToolDir}SymMgr.p.o 
{ToolDir)Utilities.p.o 
{ToolDir}IOInterfaces.p.o 
{ToolDir}CursorCtl.p.o 
{ToolDir}ErrMgr.p.o 
{PInterfaces}IntEnv.p 
(PInterfaces}MemTypes.p 


Vwwvweuqguaq qq Q gq aw 


{PInterfaces}QuickDraw.p 
{PInterfaces}OSIntf.p 
Make.p.o 
{ToolDir}Stubs.a.o 
{ToolDir}CallProc.a.o 
{ToolDir}Utilities.p.o 
{ToolDir}Utilities.a.o 
{ToolDir}IOInterfaces.p.o 
{ToolDir}IOInterfaces.a.o 
{ToolDir}MemMgr.p.o 
{ToolDir}MemMgr.a.o 
{ToolDir}SymMgr.p.o 


MakeObjs 


{ToolDir}SymMgr.a.o 
{ToolDir}CursorCtl.p.o 
{ToolDir}CursorCtl.a.o 
{ToolDir}ErrMgr.p.o 
{ToolDir}MacInt.a.o 
{ToolDir}MacInterfaces.p.o 
Libs = {Libraries}Runtime.o 
{PLibraries}PasLib.o 
{Libraries}Interface.o 


VwAsWAWAWANAQ AWA WA QQ A 


QQ 


LinkOpts = -wW # no warnings (duplicates due to Stubs.a.o) 
See note © 


SourceFiles Make.p re) 
DefaultRules ) 


Makefile 
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HeeSHESHEHE Default Rule Customizations #######H hehe 
POptions = -i {Boot}ToolUnits: See note © 


HFFtHHFTHFHFHFH? Dependency Rules #####st FFF ses ges st t 


MakeX ff {MakeObjs} {Libs} See note © 
Link (LinkOpts} -p -b -o MakeX re) 
-t MPST -c "MPS " Pe) 


{MakeObjs} {Libs} 2LinkMsgs 


MakexX ff defaultRules 

Duplicate -d defaultRules MakeX -y # copy default rules into Make's data fork 
Makex ff {MakeObjs} {Libs} defaultRules 

SetFile MakeX -m . -d. - #set lLast-mod and creator dates 
Make.p.o ff {MakeUses} See note © 


Delete MakeLoad -i #delete Make's Load/Dump file if out-of-date 


Make.p.o Ff Make.p 

Save Make.p 2Dev:Null || Set Status 0 #save source before compile if changed 
Make.p.o ff {MakeUses} #will be augmented by default rules 
{ToolDir}MacInterfaces.p.o f {PInterfaces}MemTypes -p See note @ 


d 
{PInterfaces}QuickDraw.p Q 
{PInterfaces}OSIntf.p Q 
{PInterfaces}ToolIntf.p ) 
{(PInterfaces}PasLibIntf.p 


{ToolDir}MemMgr.p.o  f {ToolDir}Utilities.p.o Q 
{ToolDir}MacInterfaces.p.o @ 
{PInterfaces}MemTypes.p 
{ToolDir}SymMgr.p.o f {ToolDir}MemMgr.p.o 0 
{PInterfaces}MemTypes.p 
{ToolDir}Utilities.p.o f {PInterfaces}MemTypes.p 
{ToolDiryIOInterfaces.p.o f {ToolDir}Utilities.p.o ?) 


{ToolDir}MacInterfaces.p.o dQ 
{PInterfaces}MemTypes.p 


Backup f See note © 
Duplicate -y = MakeSre: #backup to Sony 

Restore f. 
Duplicate -y MakeSre:= : #restore from Sony 

Listings f {SourceFiles} See note © 


Print -h -r -ls .85 -s 8 -b -hf helvetica -hs 12 {NewerDeps} 
Echo “Last listings made “Date’" >Listings 
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~~ 


Notes on Make’s makefile 
@ The exported Shell variable {Boot}, used in the definition of {ToolDitr}, is 


@ 


automatically defined by Make when invoked. 


Several variables—{MakeUses}, {MakeObjs}, {Libs}, and {SourceFiles}—are used 
for lists of filenames. This is a convenience because the lists are used in several 
places later in the makefile, it also helps to reduce errors. Note that you can 
temporarily remove any file from the list by placing a comment character at the 
beginning of the line for the file. 


The {LinkOpts} variable is used to specify Linker options (and is used only once). 
This usage is handy because the definition in the makefile functions as a default 
that can be overridden from the command line with the -d option, as in 


Make -d LinkOpts='-w -1l >Map' 


The {POptions} definition gives a value to one of the variables used in the default 
rules, customizing the built-in default rules for Pascal compiles for this particular 
makefile. 


The three sets of ff rules for MakeX (an experimental version of the Make tool) 
handle (a) the Make link (which creates MakeX’s code resources), (b) the 
copying of the default miles to MakeX’s data fork (Make reads the built-in default 
rules from its own data fork), and (c) the setting of the creation and modification 
dates. The link will take place only if the MakeX objects or libraries change. The 
default rules will be copied only if the rules have changed. And the setting of the 
dates will take place if either of the first two rules was activated. (Note that the 
third rule has the union of the dependency relations of the first two.) 


The three sets of ff rules for Make.p.o control the compilation of the main 
source for Make, with some interesting side effects. The Make source uses the 
Pascal Compiler’s SLOAD option, which creates a symbol table for the Uses that 
can be loaded much faster than the Uses are normally processed. The first of the 
Ff rules is used to delete this load file (MakeLoad) if it has been invalidated by a 
change in the Uses files. This rule is interesting in that it deletes rather than builds 
something. The second of the ff rules saves the Make source before it is 
compiled, only if the source file has changed. The last of the ff rules does the 
actual compile. Note that this last rule has no explicit build commands, so it will 
be augmented by the built-in default rules, which will add a dependency relation 
(on the source file Make.p), and will supply the actual build commands for the 
compile. 


The dependency rules for MacInterfaces, MemMgr, SymMgr, Utilities, and 
IOInterfaces describe dependencies between various utility units used by Make. 
Several dependencies on library interface files are given. Dependencies among 
the utility units themselves are described by indicating a dependency on the 
object files of the lower-level (predecessor) units. These dependencies could 
have been expressed as dependencies on the source files of the lower-level units 
(because it is the source files that are read in a Uses list). However, expressing 
these dependencies on the object files has the nice property of ensuring that the 
lower-level units have been successfully compiled before the higher-level units 
are built. 


The Backup, Restore, and Listings targets are additional roots (top-level targets) 
in Make’s makefile, and thus represent other things that can be built besides 
MakexX itself. Note that the Backup and Restore targets do not actually get built by 
their build rules; thus they are artificial targets and will always generate build 
commands if they are specified on the Make command line. Note also that they 
do not have any dependency relations. 
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© The build rules for the Listings target demonstrates the use of the {NewerDeps} 
variable. The prerequisite of Listings is a list of the Make source files. The first 
build command prints the {NewerDeps} files. {NewerDeps} contains the names 
of the prerequisites that are newer than the target, that is, the source files that 
have changed since listings were last made. The last line of the build rules simply 
writes the current date into a file called Listings, which is the name of our 
target—this action results in a file that remembers when listings were last made. 
(The fact that the date is written into the file is unnecessary but convenient; the 
Echo itself is enough to change the file’s last-modified date.) 


“* Note: There are several implicit builds that will be generated as needed by the 
default rules. For example, the {MakeObjs} variable includes several assembly- 
language object files. Because {MakeObjs} appears as a prerequisite of the link 
step, these assemblies will be generated, if necessary, before the link. 


More about linking 


This section supplements the information given under the description of the Link 
command in Part II and in Chapter 9 under “Linking.” This section may be of interest 
after you’re familiar with the major MPW tools and are ready to optimize your 
programs or build procedures. 


Linker functions 


After a source file has been assembled or compiled into an object file, it contains 
OG Object code (relocatable machine language). 


OG Symbolic (named) references to all identifiers whose locations were not known at 
compile time. (These include references to routines from separate compilations 
and libraries, and references to global variables.) 


The Linker performs the following functions: 


O Sorts code and data modules into segments, by segment name. (Within a 
segment, modules are placed in the order in which they occur in the input files.) 
The -sg and -sn options allow you to change segmentation at link time. 


Note: A module is a contiguous region of memory that contains code or static 
data. A module is the smallest unit of memory that is included or removed by the 
Linker. A segment is a named collection of modules. 


Q Omits unused (“dead”) code and data modules from the output file. (These 
modules can be listed with the Linker’s -uf option, and deleted from libraries with 
the Lib command’s -df option.) 


O Provides (together with the Segment Loader) a jump table architecture that 
supports relocation of code and data at run time. (See the Segment Loader chapter 
of Inside Macintosh for more information about the jump table.) 


© Constructs jump-table entries only when needed; that is, only when a symbol is 
referenced across segments. This means the jump table will be minimum size. 


QC Edits instructions to use the most efficient addressing mode. A5-relative Gump 
table) addressing is used across segments, and PC-relative addressing is used 
within a segment. 
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Sot 


O Provides (with the data initialization interpreter) support for relocation of data 
references at run time. (The data initialization interpreter is the module 
_DATAINIT in the libraries Runtime.o and CRuntime.o.) 


O Generates a cross-reference listing of link-time (object-level) names (-x option). 


OQ Generates a location map for debugging or performance analysis (-1 option). 


The Linker copies linked code segments into code resources in the resource fork of 
the output file. By default, these resources are given the same names as the 
corresponding segment names. 


‘ Note: If Linker errors or a user interrupt cause the output file to be invalid, then 
the Linker sets the file’s modification date to “zero” Gan. 1, 1904, 12:00 a.m.). 
This action guarantees that the Make command will recognize that the file needs 
to be relinked, and that the MPW Shell will not run the file. 


Segmentation 


Segmenting a program makes it possible for unused parts of the program to be 
unloaded and purged from memory, thus freeing up memory space. You specify the 
name of a segment by placing a directive in your program’s source file—see the 
appropriate MPW language reference manual for information. Each segment is 
linked into a separate code resource. 


** Note: For a desk accessory or driver, the code must be in a single segment, and 
no jump table is constructed. Segmentation applies only to applications and 
MPW tools. 


The Linker sorts object code into load segments by name, allowing you to organize 
your source code for clarity and understanding. You can specify the same segment 
name more than once—the Linker collects code for a given segment name from all of 
the Linker input files and places it into a single segment in the output file. 


Caution 


Segment names are case sensitive. For example, “Seg]” and “SEG1” are not 
equivalent names. If you aren’t sure about the cases used, you can use the 


Linker’s -p option to get a Iisting. 


By default, resources created by the Linker are given resource names identical to the 
corresponding segment names. Link provides options for combining and renaming 
segments at link time (-sg and -sn). If you don’t specify a segment name before the 
first routine in your file, the main segment name (“Main”) is assumed there. 
Normally, you should give the main segment the name Main. 


By default, segments are limited to 32760 bytes. This limit ensures compatibility with 
all versions of the Macintosh ROM. Larger segments are allowed with the Linker’s -ss 
Option. 


“* Note: Object code is placed in a segment in the order that it’s encountered in the 
input file. For segments larger than 32K, the order is important because 
PC-relative offsets are limited to 32K by MC68000 instructions. 


For more information about segmentation, see the Segment Loader chapter of 
Inside Macintosh. 
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segments with special treatment 

When linking a main program, the Linker creates two segments that don’t appear in 
the input object files: 

0 The jump table ((CODE' resource, ID=0), which is unnamed. 


QO The global data area (no resource), which is named %GlobalData and appears 
only in the link map file (described below). You can’t change the name 
%GlobalData at link time. 


There are also two segments that have special conventions: 


O The segment that contains the main program entry point ('(CODE' resource, 
ID=1), usually named Main. 


oO A segment named %ASInit, which contains the initial values for the global data 
area and code that moves these initial values to the global data area. Applications 
should unload this segment to avoid memory fragmentation. You can unload the 
%ASInit segment by calling UnloadSeg with the address of entry point _DATAINIT 
as its parameter, for example, 


UnloadSeg(& DATAINIT) ; 


In C and Pascal, this call should be the first statement in the application. In 
assembly language the call to UnloadSeg should follow the call to _DataInit. 


Setting resource attributes 


Resources have attributes that control when and how they are loaded. The default 
resource attribute values set by the Linker are shown in this table. 


Resource attributes 


‘CODE’ resource Hex Decimal 

QO (JumpTable) $20 32 resPurgeable 

1 (“Main”) $34 D2 resPurgeable+resLocked+resPreLoad 
Others $20. 32 resPurgeable 


“* Note: For linking MPW tools (programs with output file type MPST and output file 
creator 'MPS '), all segments default to resPurgeable. Make sure that you do not 
set the resLocked bit for a tool. 


The Linker option -ra sets the resource attributes. Some useful resource attribute 
values are 


$20 32 resPurgeable 
$10 16 resLocked 
$08 8 resProtected 
$04 4 resPreLoad 


For more information about resource attributes, see the Resource Manager chapter 
of Inside Macintosh. 


The Linker also sets the resChanged attribute (when a changed resource is in 
memory, and needs to be updated in the file). The Linker does not check or enforce 
settings for the other resource attribute bits. 
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Controlling the numbering of code resources 


Normally, you don’t need to worry about which segments are given which resource 
numbers. However, you may want to control the assignment of resource numbers to 
optimize program load time, to implement a specialized code manager, or to match 
the numbering produced by another linker. 


The Linker creates and numbers code resources based on the order in which it 
encounters the segment names in the command-line parameters and the input 
object files. If you can’t easily predict the order in which the names appear in the 
object files, you may want to force the ordering with command-line options that 
contain dummy segment-mapping directives. For example, the following sequence 
of Linker options forces Main to come first, followed by Init, Body, and Term: 


Link ~sn dummyl=Main # must contain the main code module @d 
# or entry point ad 
-sn %ASInit=Init ad 
-sn dummy3=Body a 
-sn dummy4=Term a 
etc. 


The “old” segment names may be either “dummy” names (which don’t appear in the 
object files) or actual mappings, such as the mapping of the %AS5Init code into the 
segment Init. 


Resolving symbol definitions 


This section describes how the Linker resolves references to symbols. For a more 
detailed discussion of local and external symbols, see Appendix F. 


Symbols in object files are either local or external. A local (module, entry point, or 
segment) can be referenced only from within the file where it is defined. An 
external (module, entry point, or segment) can be referenced from different object 
files. An entry point is a location (offset) within a module. (The module itself is 
treated as an entry point with offset zero.) A reference is a location within one 
module that will contain the address of another module or entry. 


Multiple external symbol definitions 


If the object files contain more than one definition for an external symbol, the first 
definition is used, and all references are treated as references to the first definition. 
This lets you selectively override entry points in libraries so that you can substitute 
new versions of code. When subsequent definitions are encountered, a warning is 
generated. 


Unresolved external symbols 


Occasionally, you may find that an external symbol is unresolved because a 
reference was generated with case sensitivity set one way, whereas the definition was 
generated with different case rules. When this happens, you can avoid recompiling 
by using the Linker option -ma (module alias). Whenever the Linker encounters an 
unresolved symbol, it checks the list of module aliases in an attempt to resolve it. 


More dbout linking © 
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Linker location map 


If you specify the Linker option -l, the Linker writes a location map to standard 
output. The map is produced in location ordering, that is, sorted by segNum, 


segOffset. 
The format is divided into the following fields: 
name segName segNum,segOffset [ @/TOffset] [#] [E] [C] [ fileNum, defOffet | 
For example, 
seg Main 1 
TEFROMSCRAP Main 1,422 2,12892 
TETOSCRAP Main 1,444 2,12946 
% BEGIN Main i-4ec 3,3398 
% INIT Main 1,46E 3,3420 
ete. 


size Main 7CA 


seg *GlobalData 0 


#0001 tGlobalData 0,0 # 3, 2332 
__PASHEAP %*GlobalData 0,C 3, 2886 
PASHEAP %GlobalData 0,30 E 3,2892 
QUICKDRAW sGlobalData 0,FE E “44,4826 
_SAGIlbls %GlobalData 0,FE # 4,4834 
etc. 

size *GlobalData 26C 

seg %AS5SInit 3 
_DATAINIT *%ASInit 3,0 4,6338 
_DataInit SASInit 37.0 @ 32 E 4,6558 
#0001 ‘ASInit 3,C8 + 4,6574 
_ASInit $ASInit 3,C8 E 4,6586 


size %AS5Init C8 


G /TOffset is a hex number giving the distance from the memory location pointed to 
by register AS to the jump-table entry of the symbol. 


OG The number sign (#) indicates a local symbol, that is, not necessarily a unique 
name. 


Q The symbol “E” indicates an entry point in the immediately preceding module. 
Q The symbol “C” indicates that this module contains initialized data. 


O FileNum and defOffset are hex numbers giving the file number and offset within 
the file where the symbol is defined. They are included only if the -Lf option is also 
specified. 


The map of static global variables is presented as a data segment named 
%GlobalData. The offsets in this segment are positive—the zero byte is furthest below 
A5, and the highest-offset byte is the byte immediately below AS. In order to 
translate these positive offsets into negative offsets from A5 (as shown by the 
debugger), you need to subtract the size of %GlobalData from the offset. 


No map information is provided for the data initialization descriptors, which are 
appended to segment %ASInit. 
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Optimizing your links 


Because of the complexity of the Linker’s functions, the Link step is often the longest 
single step during incremental rebuilding of your program. The following steps can 
substantially speed up the Linker’s performance: 


OQ Use @ RAM cache. The Linker must open and close many object files (particularly 
with the -bf option). Experience has shown that large links run up to four times 
faster when you use a RAM cache of 64K or more on machines with at least 1 
megabyte or more of RAM. (Use the Control Panel desk accessory to check your 
RAM cache settings—if you change the setting, you must restart the MPW Shell to 
have the new setting take effect.) 


O Use the Lib utility to combine input files. You can use the Lib command to reduce 
the number of input files so that the -bf option is not needed. Using Lib can give a 
10-15% improvement in link speed. See “Library Construction” later in this 
chapter. 


O Eliminate unneeded files. You can eliminate unneeded input to the Linker by 
heeding the warning “File not needed for link,” and deleting the files that are so 
identified. This means customizing your link lists, rather than relying on a generic 
makefile for linking. 


O Eliminate unneeded references. You can also eliminate unneeded input by using 
Lib to remove unreferenced modules. Experience has shown that producing a 
specialized library file can increase Linker speed by as much as 40%. See the next 
section, “Library Construction.” 


Library construction 


The Lib tool enables library construction by allowing you to combine object code 
from different files and languages into a single object file. For example, you can 
combine assembly-language code with C or Pascal. The Lib tool was used for this 
purpose in constructing the libraries distributed with MPW. 


The Lib tool and its options are described in Part I]. This section explains some 
aspects of using Lib. 


Lib reorganizes the input files, placing the combined library file in the data fork of 
the output library file. By default, the library output file is given type 'OBJ ' and 
creator 'MPS '. Lib’s output is logically equivalent to the concatenation of the input 
files, except for its optional renaming, resegmentation, and deletion operations, 
and the possibility of overriding an external name (as in Link). Lib doesn’t combine 
modules into larger modules, nor does it resolve cross-module references. This 
limitation guarantees that the output of a link that uses the output of Lib is the same as 
that of a link using the “raw” files produced by the Compilers and Assembler. 


Object files that have been processed with Lib result in significandy faster links than 
the “raw” object files produced by the Compilers and Assembler. There are several 
reasons for the speed improvements: 


OG Code and Data modules are separated into different sections, and Code modules 
are further sorted by segment name. These actions improve the performance of 
Link, which must sort input modules into output code resources. 


qj All of the named symbols in the object file are gathered into a single Dictionary 
area at the start of the file. This makes the output file smaller and simplifies the 
processing needed by Link to resolve references. 
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Q When several object files are combined, multiple instances of a symbol definition 
are replaced by a single definition. Again, this makes the output file smaller and 
simplifies the processing by Link. 


Lib correctly handles file-relative scoping conventions, such as nested procedures in 
Pascal, static functions in C, or ENTRY names in Assembly; that is, it never 
confuses references to an external symbol with references to a local symbol of the 
same name, even if the two symbols are in two files combined with Lib. 


Using Lib to build a specialized library 


Each of the language libraries has files that you may or may not need to link with, 
depending on the functions your program calls. (See Appendix A.) Once you 
determine which files are needed for linking a particular program, you can greatly 
improve the performance of subsequent links by combining libraries into a single 
specialized library file. In building a specialized library, you can use Lib to 


Q change segmentation (with the -sg and -sn options) 
O change the scope of a symbol from external to local (with the -dn option) 
OQ delete unneeded modules (with the -dm option) 


Lib’s renaming, resegmentation, and deletion operations give you detailed control 
over external names, the contents of library files, and the segmentation of object 
code. To use these features, you may need to review some of the material in 
Appendix F in order to understand how modules and entry points are represented in 
object files. The DumpObj command is also useful in exploring the contents and 
structure of the library files provided with MPW. 


Removing unreferenced modules 


You can eliminate unneeded input to Link by using Lib to remove unreferenced 
modules. You can determine the number of unreferenced modules from the Linker’s 
progress information. (Use the -p option.) The Linker reports the total number of 
symbols read, as well as the number of active symbols (that is, the symbols in the 
output), and the number of visible symbols (that is, the symbols requiring jump- 
table entries). For example, 


155 active and 54 visible entries of 714 read. 


The difference between the total read and the number of active symbols is the 
number of unreferenced (and unneeded) symbols. Most of these unreferenced 
symbols represent standard library functions that your particular program doesn’t 
require. 

Unreferenced modules can be removed in three steps: 

1. Use the Linker’s -uf option to produce a file containing the unreferenced names. 


2. Use the -uf file produced by Link as the input to Lib, using the Lib option -df to 
produce a specialized library that contains only the modules that your program 
requires. 


3. Use the output of Lib as the input to subsequent links. 
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Guidelines for choosing files for a specialized library 


The choice of files to include in a specialized library file is largely dictated by 
“stability” issues: Files that are unlikely to change for many builds are the best 
candidates. “Stable” files include the library files provided by Apple for the ROM 
interfaces and for language support. Files that are under development are best left as 
single files. 


Should you find it necessary to change one of the component files of a specialized 
library, you don’t always need to immediately rebuild the specialized library. You 
can simply include the newer version of the object file in the link list, before the 
specialized library file that contains the older version. You'll get some warning 
messages about duplicate symbols, but all references will be correctly moved to the 
first definition encountered by the Linker. Later, after the file is stable again, you can 
rebuild the library. 


Library construction 
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Chapter 11 


Debugging With MacsBug 


This chapter describes the theory and operation of MacsBug, the Macintosh 
MC68xxx debugger. It also describes the syntax of commands accepted by MacsBug. 


About MacsBug 


MacsBug is a line-oriented, single-Macintosh debugger. It resides in RAM along with 
the program being debugged. The capabilities of MacsBug include 


oO 


displaying and setting memory and registers 
disassembling memory 

stepping and tracing through both RAM and ROM 
monitoring system traps 


Oo Oo O 


O displaying and checking the system and application heaps 


MacsBug obtains control when certain MC68000 exceptions occur. You can then 
examine memory, trace through the program, or set up break conditions and 
execute the program until those conditions occur. 


MacsBug works with the following hardware configurations: 

Q 512 kilobytes to 4 megabytes of RAM 

O 64K or 128K ROMs (Macintosh Plus) or 256K ROMs (SE and I) 
QO Motorola 68000 or 68020 processors 

O Motorola 68881 floating-point coprocessor 


‘+ Note: MacsBug does not work on the Macintosh XL. Macintosh XL users should 
use MacsBug.XL, which is also provided. 


Installing MacsBug 


MacsBug is not a normal Macintosh application. Instead, MacsBug installs itself 
Once at boot time and remains active until shutdown. Installation occurs if the 
following conditions are met: 


1. MacsBug exists and is named “MacsBug’”. 
2. It is on a startup (bootable) disk. 


3. It is in the current System Folder. The System Folder is, by definition, the folder 
that contains a system file named System and a system file named Finder. 


MacsBug is shipped on the MPW distribution disk #1, you must move MacsBug to the 
System Folder to install it 


After a successful installation, the message “MacsBug installed” is displayed below 
the “Welcome to Macintosh” message. The startup application (normally the 
Finder) is then launched as usual. 


Once MacsBug is installed, the only way to remove it is to reboot. To prevent the 
installation of MacsBug during a boot, hold the mouse button down while booting. 
To permanently override the installation of MacsBug, simply rename it or remove it 
from the disk. 
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“* Using HFS with the 64K ROM: If you have MacsBug on an HD-20 (HFS) Startup 
disk on a machine with the original 64K ROM, there is a seeming conflict with the 
above mouse-down command, because holding the mouse button down at boot 
also forces the Macintosh to boot from the floppy disk rather than switch- 
launching to the HD-20. However, a skillful mouser can accomplish either 
command simply by knowing that MacsBug is installed first, right after the 
“Welcome to Macintosh” hello message, and that the HFS code looks for a 
mouse-down only after the “MacsBug installed” message. 


Theory of operation: a technical aside 


This section provides background information about how MacsBug works. This 
information is important if you are interested in implementing your own Macintosh 
debugger; most other readers can skip this section. 


The boof process 


The state of the world when MacsBug is about to be loaded is fairly complete. The 
interrupt system, Memory Manager, and ROM-based I/O drivers have already been 
initialized by the ROM boot code. The boot code initializes the Event Manager, the 
Font Manager, the Resource Manager, and the file system. (Although the Toolbox is 
initialized at this point, MacsBug does not use the Toolbox.) The 'DSAT' table is 
loaded in and the string “Welcome to Macintosh,” contained therein, is displayed. 


Next, the loading process of MacsBug takes place as follows: First the boot-blocks 
code reserves some space (1024 bytes) for MacsBug’s own global variables. Then this 
code looks for the file specified in the boot blocks, as described above. If the file is 
not found, then the global space is deallocated and the boot process continues 
normally without installing a debugger. 


If MacsBug is found, the data fork (not the resource fork!) of the file is loaded onto 
the current stack, which is located immediately below the main screen buffer in 
memory. 


“* Historical note: For reasons relating to the original Lisa Workshop, the first block 
(512 bytes) of the MacsBug data fork is stripped off during this loading process. 


The boot code then JSRs to MacsBug itself. MacsBug begins its installation process by 
checking to see if the mouse button is down. If it is, MacsBug aborts the installation 
and lets the boot process continue without installing itself. If the button is not down, 
MacsBug determines which kind of machine and microprocessor it is running on, 
and configures itself accordingly. 


At the successful completion of the installation, the message “MacsBug installed” is 
posted below the “Welcome to Macintosh” message. The boot process then 
continues by loading 'INIT' resources from the System file. 


om 


% 


Technical note: The boot code looks for 'INIT' resources 0-31 and JSRs to them. 
These 'INIT' resources are used to set up the keyboard maps CINIT's 0 and 1), install 
patches (of type 'PTCH') to ROM code, and so on. 'INIT' 31 extends the system 
further by looking for any files of type INIT in the System Folder. This facility 
allows you to install your own startup code without changing the System file. 


Finally, the startup application is launched. The startup application is typically the 
Finder, but can be set to any other application via the Finder’s “Set Startup” menu 
item. 


Theory of operation: a technical aside 
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Memory usage 


During installation, MacsBug obtains further memory from below the main screen 
buffer for use as its own screen memory. (MacsBug obtains memory from the same 
general area in RAM as do RAM disks and caching utilities, based on the location of 
BufPtr, a Macintosh global variable.) MacsBug offers a full screen display with 40 
lines saved. This display uses about 22 K of memory on a Macintosh Plus or 
Macintosh SE. The display on a Macintosh II requires about 62 K. 


The total RAM requirement of MacsBug is approximately as follows: 


Macintosh Plus and SE 


Global space 1K 
Screen space 22K 
Code space 27 K 


Macintosh II 


Global space 1K 
Screen space 62 K 
Code space 27K 


Total 50 K Total 90 K 


MacsBug may not work with some memory-intensive applications on a 

Macintosh 512K. For example, using MacsBug and the MPW Pascal Compiler on a 
Macintosh 512K severely limits the size of programs that may be compiled. Two 
solutions are possible: 


1. Remove MacsBug to free up about 50K of RAM. 


2. Add additional RAM via the Macintosh Plus logic board upgrade or a compatible 
third-party hardware upgrade to 1 megabyte or more of RAM. 


MacsBug exceptions 


When installed, MacsBug puts pointers to itself in many of the hardware exception 
vectors in addresses $0000 0000 through $0000 OOFF. It then remains dormant until 
one of “its” exceptions occurs. The following is the list of exceptions to which 
MacsBug responds; each is numbered one greater than the corresponding 
Macintosh System Error number. 


Exception # Assignment 


2 Bus error (rarely seen on the Macintosh) 
3 Address error (not aligned to a word boundary) 
4 Illegal instruction (bit pattern not recognized) 
> Zero divide 

6 CHK instruction (array index out of bounds) 

7 TRAPV instruction (overflow) 


9 Trace (used to single-step in MacsBug) 
10 Line 1010 emulator (the A-trap handler for all Toolbox traps) 
11 Line 1111 emulator (68xxx coprocessor trap interface) 
28 Level 4 interrupts 
29 Level 5 interrupts 
30 Level 6 interrupts 
31 Level 7 interrupts 
47 Trap $F instruction (used for setting programmer breaks) 


MC68000 exception processing is described in the Motorola 68000 Programmer’s 
Reference Manual. 
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Any time an A-trap or other exception listed above occurs, MacsBug intercepts the 
trap and can thus stop or display the current state of the machine. Single-stepping 
through 68xxx instructions is possible because MacsBug can set the Trace bit in the 
Status register of the microprocessor. MacsBug saves the ROM-based A-trap handler 
address in the long word immediately preceding its own A-trap handler routine. 
Thus, if you need to access the real ROM A-trap handler when MacsBug is installed, 
you can look at the long word before the address of the current handler. 


Using MacsBug 


The simplest way to get into MacsBug is to generate an exception by pressing the 
interrupt button. (The interrupt button is the rear button of the programmer’s switch 
on the Macintosh, or the minus key on the numeric keypad on the Macintosh XL.) 


To see the application screen while the debugger is active, press the tilde/back quote 
key (~/ ~) in the upper-left corner of the keyboard. To restore the debugger’s display, 
press any character key. Repeated presses toggle between the two screens, allowing 

easy viewing of both the actual code (MacsBug screen) and the results (main screen). 


The best way to enter the debugger programmatically is to set a breakpoint in your 
program by using the system trap called Debugger at the point where you want 
MacsBug to get control. There are two ways to use this trap. Calling trap $A9FF drops 
into MacsBug and displays the message “USERBRK”. It then does a normal 
exception entry into MacsBug (unless you have toggled the DX command—see 
“Break Commands’ later in this chapter). 


If you want to display custom debugging information, declare and call the trap with 
bit 10 set (S$ABFF). When this latter trap is encountered, MacsBug assumes that the 
top of the user’s stack has a pointer to a Pascal string. It prints out the string, displays 
the message “USERBRK,” and does a normal exception entry into MacsBug. As 
SABFF is a procedure call, MacsBug takes care of popping the string pointer off the 
stack. 


Here is a summary of how to declare and use this trap on a per language basis. 


Assembly language 


Declaration 
_Debugger OPWORD SAQSFF + predefined in the file ToolTraps.a 
_DebugStr OPWORD SABFF ; not predefined - define yourself 


Example cails 


_Debugger # enters MacsBug and displays USERBRK 

STRING PASCAL ; Asm directive to make sure to push a 
; Pascal string 

PEA #'Entered main loop' ; push address of string on stack 

_DebugStr ; enters MacsBug and displays message 


Using MacsBug 


Pascal 


Declaration 


PROCEDURE Debugger; INLINE SA9FF; 
PROCEDURE DebugStr(str: str255); INLINE SABFF; 


Example cals 


Debugger; {enters MacsBug and displays USERBRK} 
DebugStr('Entered main loop'); {Enters MacsBug and Displays message} 
MPW C 


Declaration 
#include <strings.h> /* Required for c2pstr() */ 


pascal void Debugger() extern OxA9FF; 
pascal void DebugStr(aString) char *aString; extern OxABFF; 


Example calls 


Debugger (); /*enters MacsBug and displays USERBRK*/ 


DebugStri(c2pstr("Entered main loop")); 
/*enters MacsBug, displays message*/ 


When MacsBug gets control, it disassembles the instruction indicated by the 
program counter and displays the contents of the registers. If the exception was 
caused by a $A9FF or SABFF instruction, MacsBug displays the message 
“USERBRK”, advances the PC to the next instruction, and then disassembles the 
instruction and displays the registers. It then displays the greater-than symbol (>) as 
a prompt, indicating that it is ready to accept a command. 


** Note: There are two other ways to enter MacsBug: by using 'FKEY’ and 'INIT' 
resources. With ResEdit, a skilled user can create a custom resource of either type 
whose sole function is described by two simple MC68000 instructions: 

SAQFF $4675 ( Debugger and RTS; that is, the sequence to enter MacsBug). 


Warning 


Another way to generate an exception that was popular in the past was to add 
a line such as 


DC.W SFECE ; generate a line 1111 exception 


at the point in your program where you wanted MacsBug to get control. (Any 
value SFOOO through SFFFF could have been used.) This method should not be 
used any more, as these instructions have been reserved by Motorola for use in 
their coprocessor interface for the 68020 microprocessor. (For example. in the 
future these “exceptions” could actually be MC48881 floating-point instructions!) 
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The MacsBug command language 


Commands consist of a one- or two-character command name followed by a list of 
zero Or more parameters (depending on the command), A return character repeats 
the last command entered, unless otherwise specified in the command description. 


Parameters can be numbers, text literals, symbols, or simple expressions. All 
parameters can be entered as expressions. Parameters are represented by 
descriptive words and abbreviations such as address, number, and expr. 


MacsBug commands can be divided into five groups: memory, break, A-trap, heap 
zone, and disassembly commands. 


Numbers 


As is fitting for a debugger, ail numbers are hex unless otherwise specified. Decimal 
numbers are preceded by a number sign (#). Hexadecimal numbers can optionally 
be preceded by a dollar sign ($). Numbers can be signed (+ or —). A hex word (four 
hex characters) preceded by a less-than symbol (<) is sign-extended to a long word. 


Here are some numbers in different formats—the formats shown are the same as 
those displayed by the CV (Convert) command, described later in this chapter. 


Number 


$FF 

37 

~FF 
#100 
+10 
#—32 
<FFFA 


Strings 


Unsigned hex 


$000000FF 
$00000037 
$FFFFFFO1 
$00000064 
$00000010 
$FFFFFFEO 
$FFFFFFFA 


Signed hex 


$O0Q000FF 
$00000037 
—$000000FF 
$00000064 
$00000010 
-$00000020 
~$00000006 


Decimal 


#255 
#55 
#-~255 
#100 
#16 
#-—100 
#6 


A text literal is a one- to four-character ASCII string bracketed by single quotes ('). If 
a string is longer than four characters, only the first four characters are used. When 
used by MacsBug, text literals are right justified in a long word. Here are some 


examples: 


String 
tat 
'Fred' 
'1234' 


Stored as 

$00000041 
$46726564 
$31323334 


The MacsBug command language 


Paz 


Symbols 
The following symbols are generally used to represent the MC68xxx registers: 


RAO, RA1,...RA7 The contents of address registers AO through A7 
RDO, RD1,...RD7 The contents of data registers DO through D7 
PC The contents of the program counter 

SR The contents of the status register 


“* Note: In any expression where you want to use the value of one of the main 
registers, use the Rx form, as shown above. If you specify AO for example, it will 
be interpreted as address AO, a valid hex address, not as register AO. 


In addition, the following symbols are used for frequently referenced locations: 


: A period (“dot”) gives the last address referenced 
TP “thePort”—the address of the current QuickDraw port 


Expressions 


Expressions are formed by operators acting on numbers, text literals, and symbols. 
The operators are 


- Addition (infix); assertion (prefix) 
- Subtraction (infix); negation (prefix) 


@ or * Indirection operator (two different prefix operators with identical 
functionality) 


Note: The indirection operator uses the long integer at the location 
pointed to by the operand. 


& Address operator (prefix) 
< Add sign-extended number (infix); sign extension (prefix) 


Expressions are evaluated from left to right. All operators are of equal precedence. 
There is no way to alter the order of evaluation. Here are some valid expressions: 


RA7+4 

3A700-@10C 

TP+#24 
-RAO+RA1-'FRED'+@@4C50 
RAS<FE34 


(RAS<FE34 is the same as RAS+FFFFFE34—useful in looking at global variables.) 
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General commands 


? 


(Help): Displays a short list of MacsBug commands and their parameters. 


DV 


(Display Version): Displays the version, the date and time of creation, and the 
signature of MacsBug. For example, 


MACSBUG 5.1Bl 17-May-86 00:05:10 <DKA> 


RB 
(Reboot): Reboots the system. 


ES 
(Exit to Shell): Invokes the trap ExitToShell, which causes the current shell to be 


launched. (The “current shell” is usually the Finder, but you can change it by editing 


the Finder field of the boot blocks.) The current shell must reside in the System 
Folder and is logically distinct from the startup application. 


°, 
* 


?° 


Technical note: ES may not work with applications that override important 


system traps. This problem occurs because the application heap gets initialized 
promptly upon calling the trap ExitToShell; the initialization usually trashes any 


system patches that were located there. However, there is a hook called 
IAZNotify, called by InitApplZone, that you can use to restore the world before 
purging the otherwise necessary routines. 


EA 


(Exit to Application): Relaunches the application. This is a faster method than 
calling ES and relaunching from the Finder. 


General commands 
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Memory commands 
CV expr 


(Convert): Displays expras unsigned hexadecimal, signed hexadecimal, signed 
decimal, text, and binary. 


DM [ address {| number} } 
(Display Memory): Displays number bytes of memory starting at address. 


Number is rounded up to the nearest 16 bytes. If number is omitted, 16 bytes are 
displayed. If address and number are both omitted, the next 16 bytes are displayed. 
The dot symbol (. ) is set to the address of the beginning of the last block displayed. 


If number is set to certain four-character strings, memory is symbolically displayed 
as a data structure that begins at address. The strings and the data structures they 
represent are 


‘IOPB' Input/Output parameter block for file I/O 
'WIND' Window record 
'TERC' TextEdit record 


(Refer to Inside Macintosh for a description of these data structures.) 


You can usually terminate a DM command by pressing the Backspace key. 


SM address expr... 


(Set Memory): Places the specified values, expr..., into memory starting at address. 
The size of each value depends on the “width” of each expression. The width of a 
decimal or hexadecimal value is the smallest number of bytes that holds the specified 
value (four-byte maximum). Text literals are from one to four bytes long; extra 
characters are ignored. Indirect values are always four bytes long. The width of an 
expression is equal to the width of the widest of its operands. The dot symbol (. ) is 
set to address. 


DBI address | 


(Display Byte): Displays a single byte of memory located at address. This 
command automatically calls the convert routine as well, allowing you to see flags 
easily. DB is useful for looking at the contents of memory-mapped I/O registers. 
(Using DM will read larger portions of memory; this can have undesired side effects 
on the peripheral chips being examined.) 


SB address [ expr] 


(Set Byte): Places the value of expr into the byte located at address. If no expr is 
given, then it clears the byte to zero. Like DB, this command is useful for debugging 
memory-mapped I/O registers. 


Dn expr] 


(Data Register): Displays or sets data register . If expr is omitted, the register is 
displayed. Otherwise, the register is set to expr. 


An[ expr] 


(Address Register): Displays or sets address register 1. If expr is omitted, the 
register is displayed. Otherwise, the register is set to expr. 
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PC[ expr] 


(Program Counter): Displays or sets the Program Counter. If expr is omitted, the 
program counter is displayed. Otherwise, the PC is set to expr. 


SR[ expr] 


(Status Register): Displays or sets the status register. If expr is omitted, the status 
register is displayed. Otherwise the status register is set to expr. 


TD 


(Total Display): Displays all of the MC68000 registers and the PC, and disassembles 
the current instruction that is about to be executed upon stepping, tracing, or going. 


TF 


(Total Floating Point): Displays all of the MC68881 registers if the floating-point 
chip is present. TF displays register values in both decimal and scientific notation. 


Fn[ expr] 


(Floating Data Register): Displays or sets the specified MC68881 floating-point 
data register 7. You can directly set the register to a decimal or scientific notation 
value. If expr is omitted, the register is displayed. Otherwise, the register is set to 
expr. 


FI { expr] 


(Floating Instruction Address Register): Displays or sets the MC68881 floating- 
point instruction address register. If expris omitted, the register is displayed. 
Otherwise the register is set to expr. 


FC [ expr] 


(Floating Control Register): Displays or sets the MC68881 floating-point control 
register. If expr is omitted, the register is displayed. Otherwise the register is set to 
expr. 


FS[ expr] 


(Floating Status Register): Displays or sets the MC68881 floating-point status 
register. If expris omitted, the register is displayed. Otherwise the register is set to 
expr. 


CS [ address1 {| address2 | ] 


(Checksum): Checksums the bytes in the range address1 through address2 and 
saves that value. The checksum is an exclusive OR of the bytes in the range specified. 
If address2 is omitted, CS checksums 16 bytes, starting at address1. If address1 and 
address2 are both omitted, it calculates the checksum for the last range specified, 
saves that value, and compares it to the previous checksum for that range. If the 
checksum hasn’t changed, CS prints CHKSUM T; otherwise it prints CHKSUM F. 


“» Note: For checksumming memory in conjunction with A-traps, see the AS 
command. For checksumming after every 68xxx instruction, see the SS 
command. 


Memory commands 
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Break commands 
BR [ address ({ count) ] 


(Break): Sets a breakpoint at address. Count specifies the number of times that the 
breakpoint should be executed before stopping the program. If countis omitted, the 
program is stopped the first time the breakpoint is hit. If address is omitted, all 
breakpoints are displayed. You can set a maximum of eight different breakpoints. 


CL [ address | 


(Clear): Clears the breakpoint at address. If address is omitted, all breakpoints are 
cleared. 


G[ address | 


(Go): Executes instructions starting at address. If address is omitted, execution 
begins at the address indicated by the program counter. Control does not return to 
MacsBug until an exception occurs. 


GT address 


(Go Till): Sets a one-time breakpoint at address, then executes instructions starting at 
the address indicated by the program counter. This breakpoint is automatically 
cleared after it is hit. 


T 
(Trace): Traces through one instruction. Traps are treated as single instructions. 


If the next instruction to be executed is a JSR to a currently unloaded segment, you will 
see the LoadSeg ($A9FO) trap instead of the JSR. Tracing through that instruction will 
not work normally. If you wish to trace through the LoadSeg trap, you need to’set a 
low-memory global at location $12D to a nonzero value. Do a SB 12D 1 to enable 
tracing through the LoadSeg call. Next, Go (G). You will break at an RTS instruction. 
Trace once CT) to see the absolute location that you are about to jump to. Trace again 
and you will be at the first step of the routine that is now loaded into memory. To turn 
off tracing through LoadSeg calls, simply execute SB 12D to clear the LoadSeg low- 
memory flag. 


S{ number | 


(Step): Steps through number instructions. If number is omitted, just one 
instruction is executed. Traps are not considered to be single instructions. Step will 
display each instruction as it is executed. 
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SS address1 [ address2 | 


(Step Spy): Calculates a checksum for the specified memory range, then does a Go; 
it then checks the checksum before each 68xxx instruction is executed, and breaks 
into MacsBug if the checksum does not match. If address2 is omitted, SS checksums 
the long word at address1. This feature is turned off by entering MacsBug via the 
programmer’s switch or by SS terminating when the checksum has changed. 


Step Spy is very slow. Step Spy is nevertheless useful for detecting what routines are 
stepping on a specific place in memory. If checking memory at every A-trap is 
sufficient for your needs, use the AS command, described below. (The slow motion 
capability of SS, however, can be useful in its own right to examine how the Finder 
zooms windows, for example. Think of it as a tool to study graphics algorithms.) 


ST address 


(Step Till): Steps through instructions until address is encountered. Unlike Go Till, 
this command does not set a breakpoint. Thus it can be used to step through, and 
stop in, ROM. 


MR [offset ] 


(Magic Return): This command lets you quickly step through an entire procedure. It 
does this by replacing the return address on the stack with an address in MacsBug. 
When the procedure returns, control first goes to MacsBug. MacsBug restores the 
original return address and then executes an RTS in trace mode. MacsBug breaks at 
the instruction after the call to this procedure. 


If offset is omitted, then MacsBug assumes the return address is on the top of the 
stack. If offset is present, then it is interpreted relative either to the stack pointer (A7) 
or the frame pointer (A6). If offset is less than A6, then MacsBug assumes that the 
return address is at A7 + offset. If offset is equal to AG, then MacsBug assumes that A6 
is the frame pointer placed on the stack by the LINK instruction as a procedure 
preamble. If offset is greater than AG, then it is assumed to be the frame pointer of a 
procedure located higher in the calling order. 


Here are some examples: 

MR 

Use MR if the called procedure has not changed the stack. 

MR n 

Use this command if the called procedure has pushed 7 bytes onto the stack. 
MR RAG 

Use this command if the called procedure has done’ a LINK instruction. 

MR @RAG 


Use this command to break after the caller of the called procedure returns. 


DX 


(Debugger Exchange): Normally, if either the SA9FF or the SABFF A-trap (two 
forms of the debugger trap) is executed, program execution halts and the debugger is 
activated. DX allows you to control whether or not program execution halts. Note 
that the SABFF trap will still print a string; thus with debugger entry disabled, an 
effect similar to that of the AT command occurs—that is, the Macintosh screen 
alternates between the debugger and the program. The default is to stop at debugger 
traps. 


Break commands 
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A-trap commands 


The A-trap commands are used to monitor “1010 emulator” traps, used to call the 
Macintosh ROM. These commands take up to six parameters (trap1, trap2, address1, 
address2, D1, and D2). These parameters indicate which traps and other conditions 
should be monitored: 


O Trap1 and trap2 specify the range of the traps. If only trap/ is specified, the 
command is invoked for trap1. If trap1 and trap2 are specified, the command is 
invoked for all traps in the range trap1 through trap2. The defaults are $A000 and 
$AA00. 


$A000-$AOFF Operating system traps 
$A800-$A9FF Toolbox traps 

0-$6F Shortcut expressions for OS traps 
$70 and greater Interpreted as Toolbox traps 


O Address1 and address2 specify a range of memory addresses within which traps 
should be monitored. The defaults are 0 and $FFFFFFFF. 


GO D1and D2 specify the values of data register 0 within which traps should be 
monitored. They are treated as unsigned numbers. The defaults are 0 and 
$FFFFFFFF. 


Thus, if no parameters are given, all traps are monitored. 


A-trap commands allow two commands to take place simultaneously. The trick to 
using the A-trap commands is to know that there are separate flags for tracing and 
breaking, and that separate globals are used for storing the general trap range (GTR) 
and the breaking trap range (BTR): 


OQ Any A-trap command (AA, BA, AT, AB, AS, AH, AR) sets the tracing flag. In 
addition, any command except AS can supply a trap range, which is always stored 
in the GTR variable. 


O Executing an AB or BA also sets the breaking flag. It also saves the trap range you 
supplied in both the GTR and BTR variables. 


In the previous release of MPW, any A-trap command would clear all flags, but in 
MPW 2.0 only AX clears all flags. If you are a “casual” A-trap user, execute AX before 
executing any A-trap commands in order to avoid undesired breaks. However, for 
the MacsBug power user, combined A-trap commands can be very useful. 


Here is an example of how you can use combined A-trap commands. If you wish to 
view (trace) all of the file system traps called from your application but also want to 
break at the next Open call that you make, you should type (and in this order!): 


>BA Open 
>AA 0 17 ~~ (Shorthand for file system traps) 


The AA command is entered second so that its range overwrites the GTR supplied by 
the BA command. This way you can view (trace) the “wider” range of traps while 
breaking on the “smaller.” 
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BA [ trap1 [ trap2 [ address1 [ address2 {| D1 [D2 ]]]]]] 


(Break in Application): Causes a break when the conditions specified by the 
parameters are satisfied and the trap is being called from the application rather than 
from the ROM. Address1 and address2 are automatically set to ApplZone and 
BufPtr. Therefore you can use this command to get back to the application when in 
ROM. Simply type BA, (return),and then G, (return), MacsBug will be entered at the 
next trap called by code located in the application heap. To break on ROM calls as 
well (or traps called from the system heap or elsewhere), use AB, described below. 


AA [ trap1 [ trap2 | address1 [ address2 [ D1 [D2 ]]]]]] 


(Application A-trap Trace): Traces and displays each A-trap called from the 
application heap without breaking if the conditions specified by the parameters are 
satisfied. AA continues to display A-traps until you press the interrupt button. AA 
allows you to monitor only the traps that the application calls, and thus can be useful 
for checking and measuring performance. To monitor all traps called, including 
calls made from inside the ROM and traps called from the system heap, use the AT 
command. 


AB [ trap1 [ trap2 | address1 [ address2 [D1 [D2 ]]]]}] 


(A-trap Break): Causes a break when the conditions specified by the parameters are 
satisfied. AB without any parameters will stop at the very next trap executed anywhere 
by the Macintosh. To stop at the next trap called by the current application, use BA 
instead: 


AT [ trap1 [ trap2 | address1 | address2 | D1 {| D2 ]))}1)] 


(A-trap Trace): Traces and displays each A-trap without breaking, when the 
condition specified by the parameters is satisfied. AT continues to display all A-traps 
until you press the interrupt button. If you wish to see just the traps called by the 
current application, use AA instead. 


For example, to see all QuickDraw calls displayed, regardless of who calls them, you 
could type 


>AT A86C A8FB 


AH [ trap1 [ trap2 [ address1 { address2 [D1 [D2 ]]]]]] 


(A-trap Heap Zone Check): Checks the heap zone for consistency just before 
executing each trap in the specified range. If an inconsistency is found, it displays the 
addresses of the two memory blocks in question. 


AR [ trap! [ trap2 [ address1 { address2 [ D1 [D2 ]}]}}] 


(A-trap Record): Whenever the parameter constraints are satisfied by an A-trap 
call, information about the call is recorded. The trap name, PC, AO, DO, and the 
time are always saved. If the call was for an OS trap, 32 bytes pointed at by AO are 
recorded; otherwise 32 bytes pointed at by A7 (the stack pointer) are saved. To 
display the current saved information, type AR with no arguments. 


A-trap’ commands 


Lists 


This command is especially useful for tracking down crashes in the Macintosh ROM. 
For example, the command 


>AR 0 1000 @2AA @114 


records traps 0 through 1000 (all traps), from ApplZone ($2AA) through HeapEnd 
($114), so it will record the last trap call made from anywhere in the application heap 
(the application’s code), 


AS address1 { address2 | 


(A-trap Spy): Calculates a checksum for the specified memory range, checks it 
before each A-trap that is called, and breaks into MacsBug if the checksum does not 
match. If address2 is not specified, AS checksums the long word at the given address. 
Use SS if you want the range of memory to be checked before every 68xxx instruction 
rather than before every A-trap only. AS is turned off by AX. 


AX 


(A-trap Clear): Clears all A-trap commands and turns off heap scrambling. 


Heap zone commands 


The heap zone commands act upon the current heap zone. When MacsBug is started 
up, the current heap zone is the application heap zone. You can set the current heap 
zone by using the HX command. Several commands cause MacsBug to scramble the 
heap zone. When you scramble the heap zone, all the relocatable blocks are 
rearranged. (See HS below.) Scrambling is useful for finding illegally used pointers to 
relocatable data structures. 


HX [ address | 


(Heap Exchange): Sets the current heap to address. If no address is given, then HX 
toggles the current heap zone between the system heap zone and the application 
heap zone. In any case, HX displays the resulting current heap address. 


HC 


(Heap Check): Checks the consistency of the current heap zone, and displays the 
addresses of inconsistent memory blocks as well as the address of the current heap. 


HS 


(Heap Scramble): Scrambles the heap zone by calling CompactMem each time a 
Memory Manager trap is called. Heap Scramble is useful for finding nil handles, 
dangling pointers, and other mistakes made in memory management. It also 
performs a heap check after each scramble. If the heap looks questionable, MacsBug 
will inform the user. Use AX to turn Heap Scramble off. 
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HD [ mask] 


(Heap Dump): Mask is optional. Whether or not mask is used, it displays each 
block in the current heap zone in the following form: 


blockAddr type size [flag MP_location] [*] [ refNum restype ID | 
Q blockAddr points to the start of the memory block. 
Q type is one of the following letters: 


F Free block 
P Pointer 
H Handle to a relocatable block 


C size is the physical size of the block, including the contents, the header, and any 
unused bytes at the end of the block. 


QO For handles (type H), flag is either blank if not purgeable or a P if purgeable. Then 
MP_location is displayed, which is the address of the master pointer to the 
relocatable block. 


Q The asterisk (*) marks any locked object (nonrelocatable blocks and locked 
relocatable blocks). 


CQ For resource file blocks, three additional fields are displayed: the resource’s 
reference number, resource type, and ID number. If mask is omitted, then the 
dump is followed by a summary of the heap blocks. If mask is present, then only 
certain types of heap blocks are displayed. Mask should be one of the following 
text strings: 


5 Relocatable blocks (handles) 
tp! Nonrelocatable blocks (pointers) 
Le Free blocks 

i ny All resource blocks 


"XXXX' Only resource blocks of the type "XXXxX' 
If mask is used, the heap summary takes this form: 
CNT ##4 <# of blocks of mask type> <#* bytes in those blocks> 
You can prematurely terminate an HD command by pressing the Backspace key. 


The dot address ( . ) is set to the last block of memory displayed by HD. 


HT [ mask} 


(Heap Total): Displays just the summary line from a heap zone dump. Mask works 
just as it does with the HD command (described above). 


SC 


(Stack Crawl): Assumes that LINK / UNLK A6 has been religiously performed at the 
beginning and end of each procedure or function. (The $D+ directive in Pascal, and 
the -g and -ga options in C, force these instructions to be performed.) The output 
format is as follows: 


SF @<stack frame location> <address of call to procedure> 
For example, 
SF @0D633C ProcName+3A 


means that the currently executing procedure or function has its local stack frame at 
$D633C and was called from ProcName+$3A (which is not the return address!). If 
the program counter is in the ROM, SC may not work properly. 


Heap zone commands 
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Disassembler commands 
SX 


(Symbol Exchange): Determines whether or not symbols are displayed. By 
default, symbols are turned on. SX affects any command that takes an address. Using 
symbols allows you to disassemble an instruction list (IL) or break (BR) on a 
procedure or function name. For example, 


>IL ProcName+58 


disassembles code starting at 58 bytes (hex) into the procedure called ProcName, 
and 


>BR ProcName+58 
sets a breakpoint at the same location. (This also works for GT, ST, DM, and so on.) 


When searching for symbols, MacsBug searches the current heap (set by the HX 
command). Macsbug goes through the current heap’s memory, looking for locked 
blocks of memory. Then, within locked blocks, MacsBug first looks for a LINK A6 
instruction followed by a matching UNLK A6 instruction. Then MacsBug looks for 
either an RTS or a JMP (AO) instruction. 


Immediately following one of these last two instructions should be an 8-character 
symbol. This symbol must be exactly eight characters long; it should be padded with 
blanks if it is less than eight characters. Some compilers set the high bit on the first 
character of the symbol, but MacsBug clears this bit. In addition, if the high bit of the 
second character is set, MacsBug expects a 16-character name (used mainly for 
method names in MacApp-generated code). To see all of the symbols that are valid 
at any given moment, use the SD command (described next). 


Turning symbols off is helpful for two reasons. First, every symbol lookup traverses 
the current heap, and therefore may degrade the speed of the disassembly. 
Secondly, if you prefer always seeing a dump of code in hex rather than symbols 
(useful when looking at ROM code, for example), turning off symbols will guarantee a 
hex dump of your code. This hex dump displays the main opcode word followed by 
two extension words which may or may not apply to the particular instruction 
disassembled. 


SD [ address | 


(Symbol Dump): Displays a list of the procedure names that can be found in the 
current heap zone. The search criteria are based on looking in each block of memory 
whose locked bit is set. In addition, a LINK A6 and its matching UNLK A6 must be 
found, followed by either a JMP (AO) or an RTS. The 8-character debugging name 
follows. Valid debug symbols must consist of ASCII characters in the range $20-$5F 
(space-underscore), inclusive. This command optionally allows you to specify a 
Starting location for the symbol dump. 
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v 


DH number 


(Disassemble Hex): Disassembles the hex byte, word, or long word input. Typing 
just one byte allows you to see the general class of instructions, as number is left- 
aligned in a long word padded to the right with zeros. (Typing DH 10, DH 20, and 
DH 30, for example, shows by induction that these instruction groups are the 
Move.B, Move.W, and Move.L classes, respectively.) 


This command is useful as a poor man’s assembler. For example, if you wanted to use 
the RESET instruction and could not remember what its opcode was, you could type 
DH 4571 as a first guess and DH would display NOP. Trying DH 4E70 as a second 
guess would reveal the actual RESET instruction. 


ID [ address | 


(instruction Disassemble): Disassembles one line at address. If address is 
omitted, the next logical location is disassembled. ID sets the dot symbol ( . ) to the 
address. 


If the code has symbols compiled with it via the $D+ directive in Pascal or the -g 
option in C, and symbols have been turned on with the SX command, each address 
is automatically displayed as a routine name plus an offset. 


IL [ address [ number} } 


(instruction List): Disassembles number lines starting at address. If number is 
omitted, a screenful of lines (typically 16) is disassembled. If both number and 
address are omitted, a screenful of lines is disassembled starting at the next logical 
location. This command sets the dot symbol ( . ) to the address. 


If the code has symbols compiled with it via the $D+ option in Pascal or the -g option 
in C, and symbols have been turned on with the SX command, each address is 
automatically displayed as a routine name plus an offset. 


You can prematurely terminate an IL command by pressing the Backspace key. 


F address count data [ mask | 


(Find): Searches count bytes from address, looking for data, after ANDing the target 
with mask. As soon as a match is found, the address and value are displayed, and the 
dot symbol (. ) is set to that address. To search the next count bytes, simply press 
Return. The size of the target is determined by the width of data; it is limited to 1, 2, 
or 4 bytes. 


For example, to find a RESET instruction in a program loaded into a Macintosh Plus, 


_,you could type 


>F CBOO EFFFF 4E70 


where CBO0 is the beginning of the application heap, EFFFF represents the length of 
the application heap (roughly), and 4E70 is the RESET instruction. 


Disassembler commands 
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WH expr 


(Where): Takes an expression, which can be a symbolic name, and displays the 
location of the first routine that it finds whose name matches the expression. ROM 
symbolic names are 10-character names; and RAM symbolic names are 8-character 
names. 


If expris less than $AA00, this command displays the address corresponding to the 
trap with that number. All of the following commented commands, for example, 
give the same result: . 


>WH EXITTOSHELL ; full name 


>WH ASF4 ; full trap word 

>WH 1F4 ; shortcut 

>WH 40F6D8 ; address of ExitToShell in the 128K ROM 
Namely, 

Trap word Address Name 

ASF4 40F6D8 EXITTOSHELL 


The shortcut method of inputting tap numbers interprets $0-$6F as OS traps, and all 
other traps as Toolbox traps. 


If expris preceded by the address operator (&), then the expression is forced.to be 
evaluated as an address. This feature is useful for examining system patches whose 
addresses are often less than $AAO00, the default address boundary. 


If expr is greater than or equal to $AA00 and less than RomBase, then the address is 
interpreted as a user routine in RAM, and a symbolic location and code segment will 
be displayed if possible. 


If expris in ROM then the trap whose code is closest to that address is displayed. 


WH is useful for finding out where you were when an error occurred. If the address 
expression is in RAM and the WH function returns “PRGM AT $$$$” you can use the 
command HD 'CODE' to list the code segments. Then, by comparing the locations 
of 'CODE' segments and the current PC, you can determine which segment you are in. 
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General commands 


? (Help) 
DV _ (Display Version) 
RB (Reboot) 


ES (Exit to Shell) 
EA (Exit to Application) 


Memory commands 


CV expr (Convert) 

DM [address { number) | (Display Memory) 
SM address expr... (Set Memory) 
DB [ address | (Display Byte) 

SB address (| expr] (Set Byte) 
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[ expr] (Data Register) 


[ expr] (Address Register) 
[ expr] (Program Counter) 
{ expr] (Status Register) 


(Total Display) 
(Total Floating-Point Display) 


{ expr] (Floating-Point Register) 

{ expr] (Floating-Point Control Register) 

{ expr] (Floating-Point Instruction Address Register) 
{ expr] (Floating-Point Status Register) 


| address1 | address2}] (Checksum) 


Break commands 


BR 
CL 
G 
GT 
T 

S 
SS 
ST 
MR 
DX 


[ address [ count} ] (Break) 

[ address | (Clear) 

[ address | (Go) 

address (Go Till) 
(Trace) 

[ number | (Step) 

address1 {| address2) (Step Spy) 

address Step Till) 

{ offset | (Magic Return) 


(Debugger Exchange) 


A-trap commands 


[ trapl [ trap2 [ addr1 [ addr2[D1[D2}]}1]]] (Break in Application) 

[ trap1 [ trap2 [ addr { addr2[D1[D2)]]]]] (Application A-trap Trace) 
[ trap1 [ trap2 {| addr1 | addr2[D1[D2]]]]}] (A-trap Break) 

[ trap1 [ trap2 [ addr1 [ addr2 { D1 { D2 ))111) (A-trap Trace) 

[ trap1 [ trap2 { addr1 [ addr2 [ D1 [ D2 )}))]1 (A-trap Heap Zone Check) 
[ trapl [ trap2 [ addr1 [ addr2[D1[D2]]]1]]] (A-trap Record) 


BA 
AA 
AB 
AT 
AH 
AR 

AS 

AX 


address1 | address2 | 


Heap zone commands 
[ address | (Heap Exchange) 


HX 
HC 
HS 
HD 
HT 
SC 


(Heap Check) 


(A-trap Spy) 
(A-trap Clear) 


[ trap1 trap2) (Heap Scramble) 


[ mask ] (Heap Dump) 
[ mask ] (Heap Total) 
(Stack Crawl) 


Disassembler commands 


SX 
SD 
DH 
ID 
IL 
F 
WH 


{ address | 

number 

{ address | 

[ address { number] ] 

address count data [ mask } 
expr 


(Symbol Exchange) 
(Symbol Dump) 
(Disassemble Hex) 
(Instruction Disassemble) 
Cnstruction List) 

(Find) 

(Where) 
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About performance measurement tools 


MPW 2.0 provides a set of performance measurement tools to aid professional 
software developers in measuring and improving the performance of their 
applications. In essence, the Program Counter (PC) register is sampled just often 
enough to obtain a statistically accurate estimate of the program’s actual use of time. 
The code is measured in “buckets” of two or more bytes and the result is output to a 
text file, PerfDump. You can then analyze these results by running a report 
generator, PerformReport. PerformReport merges the output file with a linkmap of 
the measured code resources to produce a list of procedures, sorted by the number 
of PC samples found within the procedure. 


Warning 


The performance measurement tools are designed for temporary inclusion in an 
application, desk accessory, or driver for purposes of measuring performance. 
They are not designed for inclusion in commercial products, because they rely 
on low-level system mechanisms that are not guaranteed to function correctly 
on all future machines. 


The memory management strategy for the performance tools is based on the 
assumption that developers wishing to measure performance will likely have a 
machine larger than the smallest target machine for their applications. Thus, they 
can use performance tools that require some additional memory without severely 
impacting the application’s memory management strategy. 


The best way to use these tools depends upon your particular environment and the 
code you want to test. These considerations are discussed in the section 
“Implementation Issues” later in this chapter. 


Components of performance tools 
The performance tools consist of the following pieces: 


a A library file (PerformLib.o): This file is in the {Libraries} folder. Link with this 
file. 


u Interface files for Pascal (Perf.p) and C (Perf.c): These files are in the 
interface folders: {PInterfaces} for Pascal, and {CIncludes} for C. These are the 
files that you use or include in the source files for your application. These 
interfaces depend only on the standard Macintosh memory types files: 
MemTypes.p for Pascal and Types.h for C. 


An assembly-language interface has not been provided for the performance tools. 
Assembly-language programmers can use either the Pascal or the C interface. 
Both go directly to the Pascal and assembly-language implementation in 
PerformLib.o. 


w Sample programs, makefiles, and instructions for execution: These files 
are in the Examples folders: {PExamples} for Pascal, and {CExamples} for C. For 
more details about the sample programs, see the appropriate language reference 
manuals. Instructions for running the TestPerf sample programs are included in 
the Examples folder. 
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8 PerformReport (a tool for analyzing performance data and producing 
reports): This tool is found in the {MPW}Tools: folder. For detailed information 
about the tool, see the command pages in Part II. For detailed instructions on how 
to run this tool, see the instructions in the examples folder. Examples of the output 
from this tool are discussed below. 


= ROM map files: You'll find three ROM maps in the folder {MPW}ROM.Maps: 
MaclIIROM.map, MacSEROM.map, and MacPlusROM.map. These files are 
combined with the link map file for your application, to provide symbolic 
information about the performance data. The files are used as input to the report 
generator. 


Requirements for using performance tools 


To use the performance tools, you need to add calls to these routines in your 
application, desk accessory, or driver: 


 InitPerf specifies the types of measurements to be performed, and allocates 
storage. This should be called once near the beginning of your code. 


8 TermPerf stops measurements Cif active), and frees the storage. TermPerf is 
called once after InitPerf succeeds, and measurement is finished. 


a PerfControl starts and stops measurements. PerfControl must be called once 
(after InitPerf) to start measurements. Use PerfControl to avoid taking 
measurements in idle loops, dialog boxes, alerts, and other places where the user 
response time determines performance. 


o PerfDump stops measurements (if active), and writes the performance data to an 
output file. Called after measurements are collected for reporting. 


For more details about these routines, see the appropriate language reference manual. 


How performance measurement works 


The performance measurement tools are designed to give you useful information 
about the performance of a program without severely altering the user 
responsiveness or memory requirements—that is, without changing the 
characteristics of what is being measured. However, the act of measurement 
necessarily alters what is being measured in the ways summarized below. 


Program Counter sampling 


The fundamental idea behind the performance measurement tools is to sample the 
Program Counter (PC) register frequently enough to obtain a statistically accurate 
estimate of the actual program performance, but infrequently enough so that overall 
performance is not affected. The performance measurement tools use the Vertical 
Blanking signal (VBL) on 64K ROMs and the Time Manager on 128K and larger ROMS. 


The Time Manager allows 1 ms resolution in sampling, but this imposes about a 20% 
performance degradation. A value of 4 to 10 ms reduces the performance 
degradation to 4 to 10%. Use of the VBL signal on old ROMs imposes a sampling rate 
of approximately 60 times per second (16 ms). 
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A testriction 


If your application directly uses the VIA Timer1 (or some software that uses it, such as 
the sound generator or the Time Manager) then you might not be able to use these 
performance measurement tools. On old ROMs, the performance measurement 
tools may not work correctly with programs that make use of VBL tasks. 


Warning 


If you set the sampling Interval too low for your machine, the performance tools 
may crash or cause your program fo run very slowly. It is best to start with a 
high sampling interval, such as 10 or 20 ms, and decrease if only after 
experience allows you to predict the effect of the shorter Interval. For example, 
if measurements taken with a sampling rate of 10 ms cause your program to run 
10% slower, then It is probably safe to increase the sampling rate to every 5 ms 
at a cost of having the program run 20% slower. 


Bucket counts 


The performance tools require 2 bytes of memory for a counter for each “bucket” of 
code that is measured. For instance, for a 100K tool or application, using a bucket 
size of 16 bytes, about 12,800 bytes are required for the counters. If the ROM is 
measured, an additional 8K, 16K, or 32K bytes (for 64K, 128K, or 256K ROMs) is 
required. 


If your program spends a substantial amount of time outside CODE segments and 
ROM, then you may want to measure RAM “misses.” Because RAM can be quite 
large, a second (generally larger) bucket size can be specified for RAM “misses.” 
And you can control the amount of RAM to be measured by using a low address to 
Start setting up buckets and a high address for the last bucket. If the RAM misses are 
measured, additional memory is required. 


The sum of all memory required for counters is allocated as a single contiguous block 
at the time Perflnit is called. For this reason, you should call Perflnit fairly early in 
your initialization, before memory becomes fragmented. 


In addition to the memory for bucket counters, the performance tools will use one 
master pointer for a handle to some information, and will allocate a few small 
Structures with NewPtr calls. 
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Using performance measurement tools 


This section provides a general overview of the steps necessary to install the 
performance measurement routines into your code. The MPW C and MPW Pascal 
references provide specifics for each of these steps. 


You need only make a few changes to install the performance tools in your code. The 
changes are basically the same, whether you are developing an application, a desk 
accessory, an MPW tool, or a driver. It is even possible to install performance tools 
in ROM. 


Here are the steps: 


1. Install under conditional compilation. After measuring the performance of your 
program, you will probably want to make changes, test the changes for 
correctness, and then repeat the measurements to verify the performance 
improvements. While making and testing changes, it is very important not to 
include the performance tools, unless you are confident that the changes do not 
introduce any new bugs. If your code should terminate early, for any reason, then 
the normal system recovery techniques (in MacsBug, calls such as G STOPTOOL 
under the MPW Shell or ES from an application) would not work. In such a case, 
within a few milliseconds after the system tries to reuse the memory occupied by 
the performance tools, a timer interrupt occurs and a system error results. The 
system error would probably force rebooting the system. For this reason, it is 
advisable to include the performance tools under a conditional flag. Please 
consult the appropriate language reference. 


2. Include the interface. In the main body of your code you need to reference the 
interface file for the performance tools. 


3. Provide a pointer to a block of variables. For an application or MPW tool, you 
should declare a global variable. If you are developing a desk accessory, driver, or 
ROM that does not have global variables, then you need to be somewhat creative 
in finding a location for the pointer. The choices include: a local variable on the 
stack (assuming the stack frame will persist long enough), a field of a block 
allocated and locked down in the heap, or a low memory location. In any event, 
the address of the location allocated for the pointer must be passed to the 
performance routines. 


4. Initialize the performance tools. Somewhere near the beginning of your code, 
when large chunks of memory are available, you need to initialize the 
performance tools. 


Warning 


Once your code has initialized the performance routines successfully, it is 
important that the termination routine described below be called before your 
code terminates. Failure to do so will almost always result in a fatal system crash. 
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5. Turn on the measurements. After initialization has succeeded, you can start 
measurements at any point in your code. The call that starts (and stops) 
measurements returns the current on-off state as a Boolean value, in order to 
support a wide variety of user interfaces to the tools. You can call PerfControl with 
a second argument of false in order to turn performance measurements off. This 
is useful for disabling sections of code that you don’t want to measure, such as the 
event loop of an application, a dialog box where user response time will dominate 
the compute time, parts of the application that rely on the VIA timer, and so on. 


6. Dump the results. When you reach the end of the code to be measured, you must 
make a call to have the performance counters written into a text file. If the dump 
routine encounters any I/O, memory management, or other system errors, it 
returns a nonzero return code. You can examine this code to determine the nature 
of the problem. 


7. Terminate cleanly. After dumping the counters to a text file, you must terminate 
the performance measurement tools cleanly—that is, remove the interrupt 
routine and free the memory associated with the performance global variables 
and counters. 


Performance reports 


When your code has completed its execution, a call is made to PerfDump in the 
performance meansurement tools, which generates a performance output file 
showing the results of the bucket counts. You can then analyze this data by using the 
tool PerformReport. Examples of both the performance output and report files 
appear in this section. See Part II for a command page describing the tool 
PerformReport. 


Performance output file 


The results of the performance tests are output to a performance data file when 
PerfDump is called. This file is a text file containing the bucket locations and counts. 
You should call PerfDump at the very end of the test, so that no interference with 
program I/O should occur. The performance output file is not opened until 
PerfDump is called. 


Below is an example of a performance output file as generated by a call to PerfDump. 
Some repeated lines have been omitted, as indicated by “...”. 


Notice that the performance data is arranged on a per segment basis. Only nonzero 
buckets are reported; in other words, missing buckets had a hit count of zero. 
(PerfDump has an option to produce a bar graph to the left of the Hits column. That 
option was not exercised in this example.) 
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Performance Parameters 


22a 2S Ra 2 SS 3B SVS VS STV ES VSI 


Bytes per bucket, Code and ROM: 8 
Bytes per bucket, RAM: 4 
Sampling Interval: 4 ms 


Performance Summary 


c— 2 - > 5 SF - S— &- FS FS tS ES 


Total hits outside of the sampled segments: 2 
Maximum hits in one bucket: 872 
Total hits in all buckets: 3222 


Performance Data 


Offset Hits | Seqment 117 size 20000 


52F8 Le 
5300 i 
53C8 124 
53E8 a a 
53F0 2 | 
5400 LI 
5428 b.'\l 
5728 872 | 
1B830 8: 
1B838 53 | 
1B840 41-1 
1B848 G1: 
13850 41 | 


Offset Hits | Segment 253 size I1FFFFF 


D6A0 1 | 
287D0 40 | 
1E6134 1 | 
1E8990 1 | 
1FB20C 101 | 
Offset Hits | Segment 13 size B68 name STDIO 
Offset Hits | Segment 12 size 71E name SACONSOL 
Offset Hits | Segment 5S size DO name ROMSEG2 
70 2 | 
88 5 | 
90 10 | 
BO 4 | 
B8 2 | 
co 3 | 
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Offset Hits | Segment 4 size 136 name ROMSEG1 


10 9 | 
18 3 | 
20 5 | 
110 19 | 
118 58 | 
120 46 | 
Offset Hits | Segment 3 size 8C name SEG2 
50 = | 
58 3 | 
60 9 | 
68 1 | 
70 14 | 
78 1 | 
Offset Hits | Segment 2 size DO name SEG1 
10 2 | 
18 is | 
20 4 | 
A8 7 | 
BO 12 | 
B8 18 | 


Offset Hits | Segment 1 size 101C name Main 


F38 43 | 
F40 116 | 
F48 78 | 
FSO 19 | 
F58 77 | 
F60 66 | 
F68 56 | 
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Analyzing the results with PerformReport 


Once the performance data file has been generated, you are ready to run the report 
generator, a tool called PerformReport. This tool merges the performance output 
file with a linkmap of the measured code resources to produce a list of procedures, 
sorted by the number of PC-samples found within the procedure. (See Part II for 
more information on PerformReport.) An example of the contents of this file is 
shown below. 


PerformReport -- Merges Linker Output and Performance Dump January 30, 1987 
Reading Link Map file: "temp3" 


Reading Performance Measurements file: “Perform.Out" 


PerformReport Parameters: 


8 bytes per bucket, ROM and CODE. 

4 bytes per bucket, RAM. 

2 hits outside code measured. 
3224 hits total, 0.0% outside the segments. 
872 maximum hits in one bucket. 


Procedures by possible hits (showing Probable % of time): 


Num Segment : Procedure Def Prob Poss Prob% 
117 Main : ATRAP 68020 497 436 872 28.9% 
117 Main : CHKSLOT 0 436 872 13.5% 
117 Main : DSPATCH 0 fe) 872 0.0% 
117 Main : RSECT 474 13 26 15.1% 
1 Main ; %I_MUL4 399 14 56 12.8% 
4 ROMSEG1 : ROMW100 5 0 0 0.1% 
117 Main ;: LVLIINT L 0 1 0.0% 
117 Main : TFSDISPATCH By 0 0 0.0% 
117 Main : LVL2INT 0) 0 1 0.0% 
Total Reported = 67.6% 32.1% 99.8% 


PerformReport: That's All Folks! 


Adding identification lines to a data file 


After emitting a tide line, and giving the names of the files being read, 
PerformReport has an option (-e) to echo lines from the head of the measurements 
file until the phrase “Performance Data” is encountered. This option allows you to 
add identification lines at the head of performance measurement files. Various 
parameters are gathered from lines that begin with special keywords. Here are the 
keywords with the phrases they head: 


Bytes Bytes per bucket 
Total Total hits 
Maximum Maximum hits 


Performance Performance Data 


You are free to add comment lines at the head of a data file, as long as the comment 
lines do not begin with these keywords. 


Performance reports 
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interpreting the performance report 


PerformReport translates the bucket hit information into procedure-based 
information. Because procedures can span buckets, there may be some uncertainty 
about how bucket hits are related to procedure hits. PerformReport attempts to deal 
with this uncertainty by classifying hits into several categories: 


Definite When a bucket is completely contained in a single 
procedure, all hits in the bucket are counted as definite hits 
in that procedure. 


Possible/Probable When a bucket is partially contained in several procedures, 
all hits in the bucket are counted as possible hits in each 
procedure; in addition, the hits in the bucket are counted as 
probable hits in a particular procedure, based on the 
amount of the bucket that is covered by the particular 
procedure. 


Please realize that the concept of probable hits is not intended to give an accurate 
statistical picture of the situation. What happens in practice is that buckets are 
frequently covered by two procedures, and almost all of the hits occur in one 
procedure or the other. The intent behind “possible and probable” hits is to give you 
some feeling for the accuracy of the resulting data. 


In the Pascal example TestPerf.p, the possible hits are few relative to the definite hits, 
except for the “%I_DIV4” procedure, which has zero definite hits, but shares a 
bucket with “%I_MUL4”. In fact, there are no divide operations in the sample 
program; therefore all hits belong to the multiply operations. 


If the percentage of definite hits becomes too low, you should consider reducing the 
requested bucket size. 


Implementation issues 


The performance tools have been designed to work “as is” for most common 
application, desk accessory, and driver runtime environments. However, because 
Macintosh has an open architecture, it is possible that actions taken or assumptions 
made by application code will conflict with the needs of the performance tools. This 
section discusses possible conflicts, and how to resolve them. 


Locking the interrupt handler 


You must lock down both code and data for the performance tools while 
performance measurements are being taken. Code for the trap handler must be 
locked down because the timer interrupts occur asynchronously. Data for the 
counters must be locked down because handles cannot be assumed to be valid during 
interrupt processing. The data area for counters cannot be “grown” at interrupt time, 
because the Memory Manager may not be in a consistent state. 
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Segmentation 


The code that must be locked down at execution time has been placed in segment 
“Main” and occupies about 1 kilobyte of space. This is because segment “Main” is 
usually guaranteed not to be unloaded at run time. 


If your application’s “Main” segment is too full to allow the performance tools to be 
linked correctly, then you may retarget the code in PerformLib.o by using the Lib 
tool. However, your application must not have an “unload all segments” routine in 
its idle procedure. One good segment to retarget to is “PerfMain”, because this 
segment contains some of the other pieces of the performance tools. 


These MPW commands illustrate how to retarget the code in PerformLib.o: 


Duplicate {Libraries}PerformLib.o temp 
Lib ~o (Libraries}PerformLib.o -sn Main=PerfMain temp 
Delete temp 


The first command line creates a copy of PerformLib.o in temp. The second line 
replaces the original PerformLib.o with the output of Lib. The -sn option causes all 
code originally placed in segment “Main” to be in segment “PerfMain”. The third 
line deletes the file temp. 


Dirty code segments 


Because AS is not valid at interrupt time, and there are no low memory globals 
assigned to performance measurement, the interrupt routine stores some data values 
in its code space, including the pointer to the locked-down data. Thus, if your 
application uses checksums to detect code segments attacked by errors, the 
performance tools will cause erroneous checksum failures. The easiest fix is simply 
not to checksum the “Main” segment (or whichever segment you choose). 


Movable code resources 


The code for the trap handler, and the data area for the counters, must be locked 
down during performance measurement. 


In counting “hits” in code resource segments, the performance interrupt routine 
checks that the handle to a measured resource is locked. If it is not locked, the 
resource is assumed to be “unloaded” and PC values are not checked for being within 
the resource. 


Macintosh Il ROMs and 24-bit addresses 


The performance tools currently assume that the Macintosh II is running in 24-bit 
mode, with the upper 8 bits of PC-values in a “don’t care” state, Currently,when 
doing performance measurements on the Macintosh II ROM, it appears that some 
code is running with 24-bit addresses and other code is running with 32-bit 

addresses. As a result, performance tools need to mask PC values to 24 bits to get 
consistent values. This situation may change in the future as the Macintosh Operating 
System more fully supports the 32-bit mode. 


Implementation issues 
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Writing an MPW Tool 


This chapter provides information specific to writing an integrated MPW tool. You'll 
also need to refer to the following: 


OG “Building an MPW Tool” in Chapter 9 for information about the mechanics of 
linking and installing a tool. 


O The appropriate language reference manual for details of the Integrated 
Environment routines available in the various language libraries. (The 
Integrated Environment is a set of routines, modeled on the C language, that 
provide parameter passing, access to variables, and other functions to MPW 
tools.) 


Shell facilities 


Tools running within the MPW Shell environment are provided with many facilities, 
including 


O parameter passing 

access to Shell variables 

a set of preopened files for text-oriented input and output 
I/O to windows and selections 

a means for returning status results 


signal handling (for user aborts, and so on) 


006060806~6~U0d06d (0 


exit processing 


Parameters 


Parameters are passed to tools by the Shell. Every program is passed at least one 
parameter: the name of the program itself. This parameter is always the first 
parameter (technically, parameter 0) and is useful for error messages or other 
special action. 


The text that follows the command name on the command line is first analyzed by 
the Shell for any special processing, such as filename generation or variable 
substitution. (See “How Commands Are Interpreted” in Chapter 5.) This text is then 
split up into individual words and placed in a convenient data structure for 
programmatic access. 


Cc In C, the main program is actually passed three parameters, 

. named argc, the argument count; argv, the argument 
vector; and envp, the environmental pointer [described 
below under “Environment (Shell) Variables”]. The value of 
argc includes the command name (parameter 0), and is thus 
always one more than the number of parameters to the 
command. argv is a pointer to a zero-terminated array of 
pointers to the parameters, each of which is in C string (zero- 
terminated) format. (See Figure 13-1.) 
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Pascal In Pascal, the parameters are accessible as the unit global 
variables argc and argv from the IntEnv (Integrated 
Environment) unit. As in C, the value of arge is one more 
than the parameter count, argv is a pointer to a null- 
terminated array of Pascal string pointers. 


Assembly language —_ The Integrated Environment routine, _RTInit, can be used to 
access the command parameters in assembly language. The 
addresses of argv and argc are passed to _RTInit, which 
initializes them. See Appendix I of the MPW Assembler 2.0 
Reference for details about this routine. 


C and Pascal examples are shown in Figure 13-1. 


C Sample.o -a Sample Pascal Sample.p -a Sample 


Figure 13-1 
Parameters in C and Pascal 
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Environment (Shell) variables 


The MPW Shell maintains a set of state variables that can be made available to tools 
with the Export command. When a tool is run, the Shell makes a copy of the names 
and string values of all exported variables and passes this list to the program. The 
tool can then determine the value of a variable by one of two methods: 


© doing a linear search of the list of variables until the desired variable name is 
found 


Q using the getenv function 
Because only a copy is passed, a tool cannot alter the Shell’s value of a variable. 


C Shell variables are accessible in C via the third parameter to 
the main program, called envp (the environment pointer). 
envp is a pointer to a zero-terminated array of pointers to 
name/value C-string pairs. (Each pair is of the form 
name Qvalue 0.) The C library provides the getenv routine, 
which, given a variable name, looks up its value. 


Pascal Pascal programmers are provided with another IntEnv unit 
global variable, also called envp. The structure used is the 
same as that for C, except that pointers to strings are forced to 
even byte boundaries by zero padding, if necessary. To 
facilitate the lookup of values for given Shell variables, a 
routine called IEGetEnv is provided in the IntEnv unit. 


Assembly language The Integrated Environment routine, _RTInit, can be used to 
access Shell variables in assembly language. The address of 
envp is passed to _RTInit, which initializes it. You can 
choose Pascal or C strings. You can use getenv for C strings, 
or IEGetEnv for Pascal strings (from the PasLib library). See 
Appendix I of the MPW Assembler Reference for details on 
calling _RTInit. 


Standard |/O channels 


Before starting a tool, the Shell sets up three text I/O channels that the tool can use to 
communicate with the outside world. These are 


Q standard input 
Q standard output 
O diagnostic output (standard error) 


By default, these channels are connected to the “console” (that is, any window on 
the screen). Program input may be typed (or selected) and entered in any window; 
program output appears immediately after the command in the same window. This 
input and output may be taken from or directed to other files by specifying I/O 
redirection (<, >, >>, 2, 22) on the command line. When the Shell encounters the 
I/O redirection notation, it opens or creates the necessary files, removes the 
redirection notation from the command line so that it doesn’t appear in the 
program’s parameter list, and then arranges for the open files to be passed to the 


program. When the tool finishes, the Shell flushes any buffered output and closes the 
files. 
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I/O buffering 


When using I/O routines provided by the language libraries, varying degrees of 
buffering are expected to occur on the standard I/O channels: 


O Input from the console is buffered until the Enter key is pressed. If there is a 
selection when Enter is pressed, the selected text is used to satisfy the console read 
request; otherwise, the entire line that contains the insertion point is given to the 
reader. 


Note: The MPW method of reading input creates a difficulty for interactive tools 
that write prompting text and pause to read a response entered on the same line: 
The tool will receive the prompt back as part of the line read, unless there was a 
selection when Enter was pressed. 


O When input is taken from a file, the I/O package will, by default, read the data from 
the disk in 1K blocks. 


QO Text written to standard output is also buffered 1K at a time before being sent to a 
file or to the console. (As a convenience, when a read request is issued from the 
console, all output buffers are flushed so that any prompting text will appear 
before the program pauses waiting for input.) 


O Text written to the diagnostic channel is buffered one line at a time, so that error 
messages and progress information appear in a timely manner while the program 
is executing. 


Note that this buffering can cause apparently anomalous behavior: In particular, if 
both standard output and diagnostic output are directed to the console, the order of 
the output on the screen may not match the order in which the data was written.This 
change in order may result because the separate buffers are flushed at different 
times, as illustrated in Figure 13-2. You can circumvent this problem by flushing 
standard output before writing to diagnostic output. 


“* Note: Figure 13-2 shows the output conventions in C and Pascal. Assembly- 
language programmers must do their own buffering, or call C or Pascal routines. 


File 
1K buffer 1K buffer 
Standard 
output 
Standard 
input 
OR 
Standard 
diagnostic 
Console Entered text 


(typically 1-line buffer 


1 line) 


Figure 13-2 
I/O buffering 


Shell facilities 


Cc The standard I/O files are available for reading or writing in C, via the file 
descriptors 0, 1, and 2, or the StdIO stream descriptors stdin, stdout, 
stderr. These descriptors are fully documented in the MPW C 2.0 
Reference. 


Pascal _In Pascal, the program parameters Imput and Output correspond to the 
standard input and output channels. A text file variable called 
diagnostic, which is connected to the standard diagnostic channel, is 
available from the IntEnv unit. The use of these parameters is documented 
in detail in the MPW Pascal 2.0 Reference. 


1/0 to windows and selections 


The MPW environment also provides to tools the ability to read and write to windows 
or to selections within windows. No special programming is required to use this 
feature. The MPW Shell monitors file system calls, and intercepts those that refer to a 
file that is currently open as a window. These calls are redirected automatically to the 
window rather than the file. (Thus, any modifications to the file do not become 
permanent until the window is saved.) 


Accessing selections within windows is equally transparent to programs. All that is 
required is that the filename contain the selection suffix (.§). Reading from a 
selection is the same as reading from a file, and the beginning and end of the 
selection are treated as the bounds of the file. However, writing to a selection 
replaces the selection and has the interesting property that the data written is inserted 
into the file, rather than overwriting the data that follows. 


Because window and selection I/O is handled automatically by the MPW Shell, tools 
should simply assume that they are always dealing with files. 


Signal handling 


The MPW environment provides a set of routines to handle signals. A signal is an 
event that diverts program control from its normal execution sequence. 


** Note: The only signal currently supported is Command-period, the standard 
Macintosh command for terminating the execution of an operation. 


Signals can be caught, held and released, and ignored. The default action of any 
signal is to close all open files, execute any exit procedures (described below in “Exit 
Processing”), and terminate the program. If, however, your program requires 
special handling of a signal, or chooses to ignore it, you can use the procedure 
sigset to replace the default signal handling procedure with your own procedure. 
Your program can also temporarily suspend action on a signal (for instance, before 
entering a critical section of code) by calling sighold. You can restore the signal by 
calling the procedure sigrelease, whereupon the signal handling procedure will 
take affect if the signal was raised during the hold period. Your program may also 
pause until one or more signals are raised by calling the procedure sigpause. See 
the MPW language reference manuals for the details on how to use these routines. 
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Exif processing 


A program often requires some special processing before terminating. You can use 
the procedure onexit to register a procedure to be called at program termination or 
when the exit procedure is called. This procedure guarantees your program a chance 
to do any cleanup before terminating. Exit processing is especially useful for 
cleaning up after an uncaught signal. 


Status codes 


Every tool is expected to return a status code to the Shell when it terminates. The 
Shell inspects this result—if the status code is nonzero and if the Shell variable {Exit} 
is nonzero (the default), the Shell terminates the execution of the current command 
file. The Shell also converts the result to string form and creates a Shell variable 
called {Status} with that value. The variable can then be tested with the Shell 
command language and action can be taken based on its value. 


The following conventions are used for status codes: 


0 Success 

1 Command syntax error 

2 Some error in processing 

3 System error or insufficent resources 


* Note: Only the bottom 24 bits of a tool’s status code are returned to the Shell. 
The remaining codes (including negative numbers) are reserved for use by the 
Shell. 


You may want to return error codes other than these. In that case, you should 
carefully document the numbers and their meanings. 


Cc Result codes are returned from C tools as the function result of 
the procedure main() or by passing them as the parameter 
to the C Library exit function. 


Pascal Pascal programmers must call the IntEnv procedure IEexit to 
return the status result. 


Assembly language _— The Integrated Environment routine _RTExit is available to 
assembly-language programmers. _RTExit takes the status 
code as a paramteter. 


Shell facilities 


Restrictions 


Tools are similar to desk accessories in that they coexist with another program (the 
MPW Shell), and many of the same restrictions apply to tools as to desk accessories. 
(See “Writing Your Own Desk Accessories” in the Desk Manager chapter of Inside 
Macintosh.) The following sections touch on some of the considerations in enabling 
tools to coexist with the Shell. 


Initialization 


Because tools run with the Shell, most Macintosh Toolbox initialization calls are not 
necessary and should not be called. In particular, you should not make the following 
calls: 


InitFonts 
InitWindows 
InitMenus 
TEInit 
InitDialogs 
MaxApplZone 
SetApplLimit 
SetGrowZone 
InitResources 
RsrcZonelInit 
ExitToShell 


(Note that this is not an inclusive list.) 


If your program uses QuickDraw or any routine that uses QuickDraw, be sure to call 
the InitGraf routine. This routine is necessary when using QuickDraw, because 
QuickDraw uses register A5-relative global variables, and tools have their own private 
A5 global area. Even a simple call to the QuickDraw function Random will not work 
properly unless InitGraf is called. 
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Memory management 


The Shell and tools execute out of the same heap and share the same stack. When a 
tool is started, the Shell allocates an area in the heap for the tool’s globals and jump 
table, adjusts the global register A5 to point there, and then “calls” the tool. Any 
dynamic stack space required is allocated on the same stack, and any heap objects 
created go into the same heap. 


Shell globals 


———— Ad—Stack frame pointer 
A7—Top of stack 


A5—Globals (Shell) 


Heap 


Tool globals 


A5—Globals (Tool) 


System stuff 


Low memory 


Figure 13-3 
Memory map 


When a tool terminates, the Shell restores the registers to their previous values and 
deallocates the tool’s global area and any other pointers and handles in the heap that 
may have been left allocated. The tool’s resources, however, are not deallocated 
immediately. They are unlocked and made purgeable so that the space can be used if 
needed. This practice allows for a quick restart of the tool if it is still in memory, but 
with no memory wastage penalty should the space be needed for other purposes. 


Warning 


Although the Shell releases memory that has been allocated by the tool, 
sometimes the Shell has Insufficient information to determine the owner of a 
master pointer. When a master pointer is NIL. if cannot be released by the Shell 
and cannot be reused. 


NIL master pointers are produced as a result of calls to EmptyHandle, and by a 
number of Resource Manager actions. For example, a GetResource with ResLoad 
set to FALSE will create a NIL master pointer. If this is followed by a 
DetachResource or RmveResource, the handle remains as a NIL pointer. 


It is always good programming practice to clean up handles after they have 
become obsolete. Use DisposHandle to get rid of such obsolete handles. 


Restrictions 
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Heap 


Because the Shell and tools share the same heap, some cooperation is necessary to 
ensure efficient use of the heap. Before a tool is started, the Shell makes many of its 
heap objects unlocked and purgeable. The Shell’s memory-resident code is kept as 
low in the heap as possible. The tool’s code should be moved as high in the heap as 
possible. This is done automatically, if the locked bit is not set on the tool’s code 
resources (the default from the Linker). When allocating heap space, tools should 
attempt to allocate no more space than is needed so that objects aren’t needlessly 
purged from the heap. 


When there is insufficient memory space to mn a tool, you can make more space 
available in several ways: 


Q If you are using RAM caching, you can reduce the size of the cache. 


O You can free up about 45K by running without the debugger (that is, name it 
something other than MacsBug and reboot, or hold down the mouse button while 
booting). 


O You can minimize the number of windows open when the tool is run. (Certain 
memory-resident data structures are required for each window.) Directing 
program output to a file instead of a window will also provide the tool with more 
memory. 


© You can also reduce the stack space by using the Shell resource described in the 
next section. 


Stack 


When the Shell starts up, it immediately grows the heap to its maximum size based on 
the maximum stack size. The default maximum dynamic stack size is 10K bytes when 
less than 480K is available for the application heap; the default maximum dynamic 
stack size is 20K when more than 480K is available. Because some tools may require 
more stack space or more heap space, 'HEXA' resource number 128 is available in 
the Shell to adjust the maximum stack size. 


“» Note: Because the stack is shared between the Shell and the tool, executing tools 
from within nested command files results in less stack space for the tool. The 
Shell uses about 200 bytes of stack per nesting level. 


Windows, graphics, and events 


The creation of windows, use of graphics, and event processing by tools is a largely 
unexplored area in the MPW environment. MPW aims to support these types of 
tools; however, little work has been done so far in this area, and unknown restrictions 
may exist. 


13-10 Chapter 13: Writing an MPW Tool 


Conventions 


MPW tools adhere to a certain style that allows them to work well together in an 
integrated fashion: 


O Tools take their inputs as command-line parameters, rather than prompting for 
input. This input style allows their execution to be automated and allows them to 
take advantage of the Shell’s command-line processing features such as variable 
substitution and filename generation. 

O Deviations from a tool’s standard behavior are specified with command options. 
Options may be specified anywhere on the command line and their order is not 
significant. 


QO Tools operate on a list of filename parameters, not just one, allowing the Shell’s 
filename generation feature to be exploited. 


G When no file parameters are given, tools take their input from standard input and 
write their output to standard output. The use of standard I/O allows the piping of 
the output of one program into the input of another. For example, 


Files | Count -Ll 


This command sends the output of the Files command into the input of the Count 
command, yielding the number of files and directories in the current directory. 

Q Most tools operate silently as they process their input. Visual feedback is provided 
by the spinning cursor. If more feedback is desired, a -p (progress) option is 
usually provided to send status and summary information to the diagnostic output. 

O Error messages are in the form of Shell comments or are “executable” so that the 


error can be easily located. For example, the language translators report errors in 
the form 


File "Test.c" ; line 25 ### expected: ';' got: name 


This message may be directly executed, to open the file and select the offending 
line. (See “Executable Error Messages” in Chapter 5.) 


See the “Command Prototype” section at the beginning of Part II for more 
information on MPW command language conventions. 


Conventions 
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Chapter 14 


Creating a Commando 
Interface for Tools 


About Commando 


MPW 2.0 provides a dialog interface that makes it easier to use the MPW tools and 
scripts. A dialog is the programmed interaction between a user and a tool. A dialog 
box is the graphical vehicle used to display the various controls available for a tool or 
script. A dialog may employ several nested dialog boxes. 


You implement dialogs for MPW tools by using Commando. This program looks in 
the resource fork of a tool or script for a resource of the type ‘cmdo’, that is, any 
dialogs to be used by the tool. Commando then loads the resource, builds a dialog 
list, handles events, and passes the command line back to the Shell for execution. 


You can create a dialog interface for your own MPW tools and scripts. This chapter is 
a guide to creating the resources Commando requires to operate the dialog. 


The MPW 2.0 Shell has several features that support Commando. The ellipsis 
character (three closely spaced periods obtained by pressing Option-semicolon) is 
reserved as a way to invoke Commando. When you enter an ellipsis at any point in a 
command line, the Shell will first carry out all alias and variable substitutions and 
then pass the entire command line to Commando. The output of Commando is then 
executed by the Shell. 


Three new Shell variables are used by Commando: 


m Aliases: This variable contains a list of all defined aliases, each name separated 
by a comma. The list contains only the names, not the definitions. Commando 
uses Aliases with the built-in command “alias”. Without this variable Commando 
would have no way of knowing the names of the existing aliases. The variable 
Aliases must be exported. 


= Commando: This variable tells the Shell which command to execute when the 
ellipsis character is present in a command line. To use the Commando tool, set 
the variable Commando to "Commando". You can use this variable to send the 
output of other tools to the Shell for execution. If the variable does not exist, then 
the ellipsis is removed from the command line and normal execution proceeds. 


a Windows: This variable contains a list of the current windows, each name 
separated by a comma. Commando uses this list to redirect input or output to or 
from existing windows. Without this variable Commando would have no way of 
knowing the names of the current windows. The variable Windows must be 
exported. 


Throughout this chapter, each type of Commando control is illustrated with an 
excerpt from Cmdo.r, found in the RIncludes folder. 


Using Commando 


This procedure has proven to be the easiest: 

1. Design your dialog boxes in ResEdit. It’s a good idea to start with a template based 
on the examples shown later in this chapter. 

2. DeRez the dialog box design and read the coordinates for your boxes and lines. 

3. Use these coordinates when you create a Commando resource file for your tool or 
script. Create the help text in a separate pass, to make sure it will fit in the available 

" space. 

4. Add the Commando resource to your tool or script. For example, 


Rez AddMenu.r -o "{MPW}MPW Shell" -a 
Rez Rez.r 7-0 {MPW}Tools:Rez -a 


5. Adjust coordinates and repeat step 4. 
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Resource description 


Cmdo.r, the resource description file for Commando, is located in 
{RIncludes}cmdo.r. 


Resource ID and name 


Any resource ID may be used for tools or scripts. Commando uses the first ‘cmdo’ 
resource it finds in the command’s resource fork. 


Commando draws an outlined button, the Do It button, in the lower-right corner of 
every dialog box. The Do It button is labeled with the name of the tool or script. 
(Normally Commando uses the name of the tool or script passed from the Shell.) 
Commando will capitalize the first character and force the rest of the characters to 
lowercase. For example, “StackSNiffER” would come out as “Stacksniffer.” 


Some people may prefer a different capitalization scheme. If you specify the 'cmdo' 
resource of a tool or script with a resource name, Commando will use that name “as 
is” as the label for the outlined button. This feature should be used sparingly; if you 
rename a tool, the previous name in the resource will still be displayed in the Do It 

button. 


Size of the dialog box 


The width of Commando dialog boxes is fixed at 480 pixels. You are free to set the 
height to accommodate the controls in your tool’s dialog box. The number 
specifying the height shouldn’t exceed 295 to be compatible with the smaller 
Macintosh screens. Specifying this height in the ‘cmdo’ resource will result in the 
screen elements shown in Figure 14-1. See Table 14-1 for other recommended 
dimensions. 


Please refer to the array declared under “ type 'cmdo' ” in the sample resource 
description file at the end of this chapter. The area labeled “Options” in Figure 14-1 
is the area reserved for your controls and options. 


Options 


Command Line 


Figure 14-] 
Basic template for a Commando dialog box 


Resource description 


The dimensions given below are not policy but recommendations. The sizes of the 
text-edit fields are important if you want to avoid text that shifts up and down slightly. 


Table 14-1 


Summary of recommended sizes for Commando screen elements 


Radio buttons 
Check boxes 
Pop-up menus 


Pop-up menu titles 


Regular entries 
Multi-regular entries 
Editable pop-up menus 
Editable pop-up titles 


Icons 


Pictures 


Tool description 


16 pixels high 
16 pixels high 
19 pixels high 


16 pixels high. Top of title starts 1 pixel below top of pop- 
up menu (that is, top of title = top of pop-up menu + 1 
pixel). 


16 pixels high 

16 pixels per line 

22 pixels high 

16 pixels high. Top of title starts 3 pixels below top of 
editable pop-up menu (that is, top of title = top of editable 
pop-up + 3 pixels). 

32 pixels high; 32 pixels wide 

Same relative bounds as the rectangle stored in the PICT 
resource 


At the bottom of the Commando dialog box is a three-line help box. The text in this 
box should be a brief, concise description of the tool, stating what it does. See the 
array declared under “type 'cmdo' ” in the sample resource description file at the 


end of this chapter. 
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Regular entry 


The regular entry control is the most generic control available. The control behaves 
exactly like the text-edit fields in conventional Macintosh dialog boxes. In addition 
to strings and numbers, the regular entry control can be used for special options that 
have no specified standard control. 


Here is the case declaration for regular entry controls: 


case RegularEntry: 
key byte = RegularEntryID; 


cstring; /* title */ 

align word; 

rect; /* bounds of title */ 

rect; /* bounds of input box */ 

estring; /* default value */ 

byte ignoreCase keepCase; /* the default value is never displayed in 


the Command window. If what the user 
types in the textedit window matches 
the default value, then that value 
isn't displayed. This flag tells 
Commando whether to ignore case when 
comparing the contents of the text edit 
window with the default value */ 


estring? /* option returned.*/ 
cstring; /* help text for entry */ 
Mulfiregular entry 


Multiregular entry controls are similar to regular entry controls, except that 
multiregular entry controls accept values that can be entered more than once. For 
example, most compilers accept some type of -define option that can be specified 
more than once. 


Here is the case declaration for multiregular entry. Note that the cstring for default 
values is the only control that passes its default values to the command line. This is an 
exception to the rule. 


case MultiRegularEntry: /* for scrollable lists of an option */ 
key byte = MultiRegularEntryID; 
estring; /* title */ 
align word; 
rect; /* bounds of title */ 
rect; /* bounds of input list */ 


byte = $SCountOf (DefEntryList) ; 
array DefEntryList { 


cstring; /* default values */ 
}e 
estring; /* option returned. Each value will be preceded 
with this option.*/ 
cstring; /* help text for entry */ 


Multiregular entry 
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Figure 14-2 shows the Defines window in the Rez dialog box with two defines entered. 
Here is the resource control for this function: 


NotDependent (}, MultiRegularEntry { 

"Defines:", 

{20, 35, 35, 125}, 

{40, 30, 120, 225}, 

{}, 

wag, 

"Type in multiple #defines here (such as LANGUAGE=French) " 
}, 


The empty braces after the Defines window coordinates indicates that there are no 
default strings. 


Defines: 


debug=true 
language=french 


Command Line: ————_——____—__ 
[rez -d debug=true -d language=french 


Figure 14-2 
Multiregular entry 


Check boxes 


The check box control is likely to be the most often used because it corresponds to 
the on/off type options typical of MPW tools. Here is the case declaration for 
CheckOption: 


case CheckOption: 
key byte = CheckOptionID; 


byte NotSet, Set; /* whether button is set or not */ 
rect; /* bounds */ 

estring; /* title */ 

cstring; /* option returned */ 

cstring; /* help text for button */ 


The byte NotSet or Set is used to set the button’s default state. The option is 
returned only when the button is not its default state. 


This resource code produces the check boxes in Figure 14-3: 


notDependent { }, CheckOption { 
NotSet, (20, 10, 36, 235}, "Show macro expansions", 
“-<print GEN", 


"Expand macros in the listing file." }, 
notDependent { }, CheckOption { 
Set, {35, 10, 51, 235}, “Allow automatic page ejects", 
"-print NOPAGE", 
"Controls whether the Assembler sends automatic page ejects 
to the listing file" }, 
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notDependent { }, CheckOption { 
Set, (50, 10, 66, 235}, "Show warning mesages", 
"“-print NOWARN", 
“Controls both the display and count of warning messages." }, 
notDependent { }, CheckOption { 
Set, (65, 10, 81, 235}, "Show macro call statements", 
"“<print NOMCALL", 
"Controls the listing of macro call statements." }, 
notDependent { }, CheckOption { 
Set, (80, 10, 96, 235}, "Show generated object code", 
"-print NOOBJ", 
"List generated object code or data for each listed line." }, 
notDependent { }, CheckOption { 
NotSet, {95, 10, 111, 235}, "Show up to 255 bytes of data", 
"print DATA", 
“Controls whether object data is shown in fule 
(up to 18 lines) or limited to one line." }, 
notDependent ( }, CheckOption { 
Set, {110, 10, 126, 235}, “Show macro directive lines", 
“-print NOMDIR", 
"Controls whether macro directives (including conditional 
and set directives) are shown in the listing." }, 
notDependent { }, CheckOption { 
Set, (125, 10, 141, 235}, “Show header lines", "“-print NOHDR", 
"Controls whether header lines are printed in the listing." }, 
notDependent { }, CheckOption { 
Set, {140, 10, 156, 235}, “Show generated literals", 
"“-print NOLITS", 
"Controls listing of literals produce by PEA and LEA machine 
instructions." }, 
notDependent { }, CheckOption ({ 
NotSet, {155, 10, 171, 235}, "Show assembly status", 
"“<print STAT", 
"Controls display of assembly status in the listing." }, 


Figure 14-3 shows a set of check boxes in their default state and again after the two top 
buttons have been clicked. 


Default state of buttons State after top two buttons clicked 
(J Show macro expansions {J Show macro expansions 

] Allow automatic page ejects C) Allow automatic page ejects 
{] Show warning messages (x) Show warning messages 

&J Show macro call statements &] Show macro call statements 
{ Show generated object code &] Show generated object code 
(2 Show up to 255 bytes of data §=| C Show up to 255 bytes of data 
{J Show macro directive lines &] Show macro directive lines 
{] Show header lines {] Show header lines 

{] Show generated literals SJ Show generated literals 

(J Show assembly status (C] Show assembly status 


Command Line: Command Line: 


asm asm -print GEN -print NOPAGE 


Figure 14-3 
setting the CheckOption default state 


Check 


boxes 
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Radio buttons 


The simplest set of radio buttons offers several mutually exclusive options. For 
example, the Print Option radio buttons in Figure 14-4 let you choose High or 
Standard or Draft. The Standard mode is the default. 


O High 
© Standard 
O Draft 


Command Line: 
test 


Figure 14-4 
Radio buttons with default setting 


Here is the case declaration for radio buttons: 


case RadioButtons: 
key byte = RadioButtonsID; 
byte = $SCountOf (radioArray) ; /* # of buttons */ 
wide array radioArray { 


rect; /* bounds */ 

estring; /* title */ 

estring; /* option returned */ 

byte NotSet, Set; /* whether button is set or not */ 
cstring; /* help text for button */ 


align word; 
}; 


To make the middle radio button the default, as shown in Figure 14-4 above, declare 
the middle Standard button set: 


notDependent, RadioButtons { 
{ 

{115, 300, 130, 400}, "High", "-q high", notset, 
"Print the selected files in the highest quality 
available from the printer.", 

{132, 300, 147, 400}, “Standard", “-q standard", set, 
"Print the selected files in the normal quality mode.", 

{149, 300, 164, 400}, "Draft", "-q draft", notset, 
"Print the selected files in the fastest way possible 

at the expense of quality." 


No option is passed to the command line box because the middle button is explicitly 
declared the default. If a button other than the default is clicked, Commando passes 
the appropriate option to the command line, as shown in Figure 14-5. 


@ High 
© Standard 
© Draft 


Command Line: — 
test -q high 


Figure 14-5 
Clicking a button other than the default 
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Suppose that in the previous example you wanted the default radio button to display 
its option in the command line. You would simply change the order in which you 
declared the radio buttons, so that the middle button would be declared first. Be sure 
that all buttons are NotSet. The result is shown in Figure 14-6. Commando will set the 
first button that it encounters if no button is specified as set. 


O High 
© Standard 
O Draft 


Command Line:— 
test ~q standard 


Figure 14-6 
No button specified as set 


“» Note: A radio button can be either dependent upon or parent to another 
control. For purposes of establishing dependency relations, a cluster of radio 
buttons is considered a single item in the resource listing. See “Control 
Dependencies” in this chapter for more information. 


Boxes, lines, and text titles 


It is recommended that you group dialog controls or functions within boxes. 
Commando supplies the facilities to draw a box (case Box), to draw a box with a tide 
embedded in the upper-left corner (case TextBox), and to create titles in any font 
(case TextTide). 


“» Note: When you draw a box around a set of controls, always list the box 
declaration after listing the other controls. Otherwise the Dialog Manager might 
confuse which control is clicked. 


Box and TextBox cannot depend on other controls, nor can other controls depend 
on them. Commando would not complain if you set up such a dependency, but the 
line or box would not respond to the state of the determining item. TextTitles, on the 
other hand, can be dependent on another control. 


Box 


Use the case Box to draw boxes around controls or to draw lines. To draw lines, make 
the rect one pixel wide. In other words, to draw a horizontal line, you might set the 
rect to {10, 10, 11, 100}. Here is the case declaration for the Box control: 


case Box: /* Can be used to draw lines too */ 
key byte = BoxID; 
byte black, gray; /* color of object */ 
rect; /* bounds of box or line */ 


Boxes, lines, and text fitles 
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TextBox 


The case TextBox lets you draw a box with the title embedded in the line at the upper- 
left corner. This is a frequently used convention in the Commando dialogs. (See the 
sample dialog box template in Figure 14-1.) Here is the case TextBox declaration 
from the Command resource file: 


case TextBox: /* Draws a box with title in upper-left */ 
key byte = TextBoxID; 
byte black, gray; /* color of object */ 
rect; /* bounds of box or line */ 
estring; /* title */ 


For example, 


notDependent, TextBox { 
gray, 
{105, 295, 169, 405}, 
"Print Quality" 

}, 


This declaration gives you the results shown in Figure 14-7. 


- Print Quality 
| O High 

© Standard 
O Draft 


Figure 14-7 
TextBox example 


TexiTitle 


Use TextTitle to draw text in any font. Here is the case declaration: 


case TextTitle: 
key byte = TextTitleID; 


byte plain; /* style of text */ 

rect; /* bounds of title */ 

int systemFont; /* font number to use */ 
int systemSize; /* font size to use */ 
cstring; /* the text to display */ 


For example, let’s write “so cool” in a cool way: 


notDependent, TextTitle { 
bold + italic, {20,20,40,100}, 
systemFont, 12, "So Cool..." 
}, 


So Cool... 
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Pop-up menus 


Pop-up menus are a convenient way to select an item from a list of related items. 
Commando manages the associated windows, aliases, fonts, and Shell variables. 
Here is the case declaration: 


case PopUp: 
key byte = PopUpID; 
byte Window, Alias, Font, Set; /* popup type */ 
rect; /* bounds of title */ 
rect; /* bounds of popup line */ 
estring; /* title */ 
estring; /* option returned */ 
estring; /* help text for popup */ 
byte noDefault, hasDefault; /* hasDefault if lst item 


is "Default Value" */ 


The last field, “byte noDefault, hasDefault”, tells Commando whether the 
pop-up menu has a default value or not. If the pop-up menu does not have a default 
value, the first value in the pop-up list is automatically selected and passed to the 
command line. If the pop-up menu does have a default value, then Commando adds 
a new item that says something like “Default Value” to the front of the list. When this 
value is selected, no value is displayed in the window that generates the pop-up 
menu. 


Here is an example of the resource code for a pop-up menu with a default value. See 
Figure 14-8 for the resulting window and pop-up menu. 


notDependent, PopUp { 
Font, 
{21, 20, 37, 60}, 
{20, 60, 39, 160}, 
“Font, 
eS ae 
“popup help message", 
hasDefault 

}, 


Y Lefauht Font 
Avant Garde 
Bookman 
Chicago 
Courier 
Geneva 
Helvetica 
Monaco 

N Helvetica Narrow 
New Century Schibk 
Palatino 

Saigon 

Symbol 

Times 


Figure 14-8 
Pop-up menu with default value 


Pop-up menus 
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Here is the resource code for a pop-up menu with no default value. The results are 
shown in Figure 14-9. 


notDependent, PopUp ( 
Font, 
{46, 20, 62, 60}, 
{45, 60, 64, 160}, 
"Font", 
i 
“popup help message", 
noDefault 

}, 


Font |Avant Garde 


/ftant Garde 
Bookman 
Chicago 
Courier 
Geneva 
Helvetics 


Monaco 


N Helvetica Narrow 
New Century Schibk 
Palatino 

Saigon 

Symbol 

Times 


Figure 14-9 
Pop-up menu without default value 


Editable pop-up menus 


Pop-up menus associated with a text-edit box can be edited. You can choose existing 
values from a list and still have the flexibility to enter completely new values. 


case EditPopUp: 
key byte = EditPopUpID; 
/* For Menuitem, this EditPopUp must be dependent on 
another EditPopUp of the MenuTitle type so that 
the control recognizes which menu item to display. 


For FontSize, this EditPopUp must be dependent on 
a PopUp of the Font type so that the control 
recognizes which sizes of the font exist. */ 


byte MenuTitle, MenuItem /* Type of editable pop-up */ 
FontSize, Alias, Set; 


rect; /* bounds of title */ 

rect; /* bounds of text edit area */ 
cstring; /* title */ 

cstring; /* option to return */ 
estring; /* help text for text-edit */ 
estring; /* help text for pop-up */ 
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The example in Figure 14-10 shows how the Font Size editable pop-up menu is made 
dependent on the current font. 


{}, 


notDependent 
Font, 
{21, 20, 37, 60}, 
{20, 60, 39, 160}, 
"Font", 
Weft, 
“Popup help message.", 
hasDefault 
}, 
Or ({1}}, EditPopUp { 
FontSize, 
{48, 20, 64, 90}, 
(45, 90, 67, 140}, 
"Font Size", 
"-=size", 
"Textedit help message", 
“Popup help message" 


PopUp { 


fant Size 


, 


Figure 14-10 
How Font Size dependency is handled 


If a particular font is selected in the Font box, then the font sizes that actually exist are 
outlined. In the example in Figure 14-11 the Monaco font has been selected in the 
Font box. The 9-point item is outlined and has been selected with the mouse. Any 
font size could be typed in the Font Size box. 


Font Size |9  Poeronn 
10 Point 
12 Potng 
14 Point 
18 Point 
24 Point 


Figure 14-11 
Font Size pop-up menu with font selected 
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Lists 


Use the case List to enable users to make multiple selections from a list of items. Four 
types of things can be listed: 

O volumes (inserted disks will be recognized and added to the list.) 

O shell variables 

O windows 

O aliases 

Here is the case declaration for List: 


case List: /* Puts up list of items & allows multiple 
selections */ 


key byte = ListID; 
byte Volumes, ShellVars, /* what to display in 


Windows, Aliases; the list */ 
estring; /* option to return before each item */ 
cstring; /* title */ 
align word; 
rect; /* bounds of title */ 
rect; /* bounds of list selection box */ 
cstring; /* help text for selection box */ 


Here is the resource code for the two examples shown in Figure 14-12. The second 
example shows that the user has already selected a window. 


notDependent, List { 
Volumes, -~ 
"Volumes", 
{20,30,35,120}, 
{37,30,101,200}, 
“Help message" 

}, 

notDependent, List { 
Windows, 
way 
“Window List", 
{20,220,35,3030}, 
{37,220,101,400}, 
“Help message" 

}, 


Volumes Window List 
HO:...: Commando:canon.r {ey 


HD:...ando:characters.h | | 


HD:...:Commando:cmda.h FF 
HD:...Commando:testt0.r ig} 


Figure 14-12 
List control 
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Three-state buttons 


Three-state buttons were invented to handle the SetFile and SetPrivilege commands. 
Both of these commands deal with the setting or clearing of flags. These commands 
also have another implicit state: “Don’t touch.” Therefore, these buttons have three 


states: Set, Clear, and Don’t touch. 


case TriStateButtons: 
key byte = TriStateButtonsID; 
byte = $$CountOf (threeStateArray) ; /* # of buttons */ 
estring; /* option returned */ 
wide array threeStateArray { 
align word; 


rect; /* bounds */ 

estring; /* title */ 

cstring; /* for Clear state */ 
estring; /* for DontTouch state */ 
estring; /* for Set state */ 
cstring; /* help text for button */ 


}e 
Here is the resource code for the example shown in Figure 14-13. 


notDependent, TriStateButtons { 
Wagt 
{ 
{40, 25, 58, 135}, “Locked™", "1", "", "L", 
"This button affects the file \"Locked\" attribute.", 
{58, 25, 76, 135}, “Invisible", "v", "", "Vv", 
"This button affects the file \"Invisible\" attribute.", 
{76, 25, 94, 135}, “Bundle", "b", "", "BS", 
"This button affects the file \"Bundle\" attribute.", 
(94, 25, 112, 135}, "System", "s", ™", "S", 
"This button affects the file \"System\" attribute.", 
{112, 25, 130, 135}, “Inited", "i", "", "I", 
"This button affects the file \"Inited\" attribute.", 
{130, 25, 148, 135}, “On Desktop", "d", "", "DM", 
"This button affects the file \"On Desktop\" attribute.", 


File Attributes 
@ Locked 
Set ———>|_ | @ invisible 
Don't touch ———»> |S Bundle 
Clear ——P| | system 
| > Inited 
| @ On Desktop 


Command Line: 
[setrite “aLb 


Figure 14-13 
Three-state buttons 


Three-state buttons 
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Icons and pictures 


Use the case PictOrIcon to place icons, pictures, or both in the Commando 
windows. This item cannot be dependent on any other item, nor other items on it. 
Here is the case declaration for icons and pictures: 


case PictOrIcon: 
key byte = PictOrIconID; 


byte Icon, Picture; /* display a picture or icon */ 
int; /* resource ID of icon */ 
rect; /* display bounds */ 


The icon in Figure 14-14 is produced by an ICON resource with an ID of.0, located in 
the system file. 


Figure 14-14 
Icon in a Commando window 


Here is the resource code that generates the example shown in Figure 14-14: 


notDependent, PictOrIcon ( 
Icon, 0, {20, 20, S52, 52} 
}, 


Control dependencies 


Sometimes one control is dependent upon the value of another control. For 
example, a font size control might be dependent on a preceding font selection 
control. In this case the font size control is termed the dependent. The preceding 
font selection control is called the parent because it enables or disables the 
dependent. 


Commando numbers each item sequentially in the order of its appearance in the 
resource description file. These numbers do not appear in the resource code; you 
must count them manually. The dependent/parent relationship in Commando is 
controlled by the sequential order of items entered into a Commando resource. 


An item may be dependent only on other items within the same dialog box. In the 
case of nested dialog boxes, the items in the second dialog box must be renumbered 
starting from one. 
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Direct dependency 


Usually dependency on another control means that the dependent control is 
disabled if the parent control is disabled (or has no value). 


Figure 14-15 shows two states of a directly dependent control. In the first case, 
nothing has been entered in the Type field, so the dependent Creator field is 
disabled and appears dimmed in the dialog box. In the second case, the Creator 
field is enabled as soon as something is typed in the Type field. 


Figure 14-15 also illustrates how the ignoreCase/keepCase flag works. Because the flag 
is keepCase and 'appl' is not equal to 'APPL', the option is displayed in the Command 
Line box. 


Crentoe 2222 | 


Command Line: 
test 


Type 
Creator({?777? | 


Command Line: 
test -t appl 


Figure 14-15 
Direct dependency 


Control dependencies 


14-17 


Inverse dependency 


A control can be inversely dependent on another control. In other words, if the 
parent is disabled, then the dependent is enabled. Or, if the parent is enabled, then 
the dependent is disabled. 


It is also possible for two controls to be inversely dependent on each other. This 
means that both controls are enabled until one is selected; then the other is 

disabled. For example, there are two types of dependencies illustrated in 

Figure 14-16. The user can select either the top check box or the bottom one, but not 
both; that is, the user is allowed to append resources to a resource file orto make the 
resource map read-only. The middle box is enabled only when the top box is 
checked, because it makes sense to replace protected resources only when appending 
to a source file. 


(J Append resources to resource file 
CJ OK ta replace protected resoures 


CJ Make resource file read-only 


& Apperid resources to resource file 
CJ OK to replace protected resoures 
O Make resource file read-only 


CJ Rppend resources {a rasourcea fila 
CJ OK {a replace protected rasoures 
{] Make resource file read-only 


Figure 14-16 
Inverse dependencies 


Here is the resource description of the three check boxes shown in Figure 14-16. To 
make a control inversely dependent on another control, make the value of the parent 
negative. 


Or { {-3} }, CheckOption { 
NotSet, 
{20, 10, 40, 350}, 
"Append resources to resource file", 
wea", 
“some help text..." 
}, 
Or ({ {1} }, CheckOption { 
NotSet, 
{40, 10, 60, 350}, 
"OK to replace protected resources", 
"-ov", 
"some help text..." 
}, 
Or { {-1} }, CheckOption { 
NotSet, 
{60, 10, 80, 350}, 
"Make resources file read-only", 
“=o, 
“some help text..." 
}, 


The second CheckOption (the dependent) is enabled only if the first (the parent) is 
enabled. The third CheckOption is enabled only if the first is disabled. 
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Dependency on the Do If button 


To make the Do It button dependent on something, you must use the special Dolt 
Button item in the Commando resource type definition. This item can be specified 
only once per resource and can be specified only in the first dialog. In the example 
shown in Figure 14-17 the Do It button is dependent on the check box. 


Test Options 
| CJ] Check me baby | 
Command Line 

Help 
This toel cannot be executed until the check box is checked. = : — 
| [= 


Figure 14-17 
Dependency on the Do If button 


Here is the resource code for the above example: 


NotDependent ( }, CheckOption { 
NotSet, 
{20, 20, 40, 200}, 
"Check me baby", 
toot : 
“Help us to help you.", 


}, 
Or { {1} }, DoItButton { 


} 


Mulltiple dependencies 


A Commando item can be dependent on one or more other items. For example, a 
control might be enabled only when two other controls are enabled. Such situations 
are considered multiple dependencies. 


Multiple dependencies may be of two types: OR and AND. In an OR dependency, a 
dependent control is enabled if any of its parents is enabled. In an AND 

dependency, the dependent control is enabled only if all its parents are enabled. It is 
possible to mix ANDs and ORs. Include an item within an AND or OR list that is 
dependent on a dummy control (case Dummy)—and make the dummy control 
dependent on another list of controls. An example appears in the next section. 


Control dependencies 
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Dependencies on radio buttons 


Commando considers a cluster of radio buttons to be one item. Remember that 
Commando numbers each item sequentially in the order of its appearance in the 
resource description file. When an item is dependent on a specific radio button 
within a cluster of radio buttons, the number of the individual button is placed in the 
upper four bits of the item number that describes the entire cluster of radio buttons. 
For example, consider a radio button cluster that is item 5 and contains six radio 
buttons. To have a dependency on button #3 you would write, in Rez syntax, 


(3<<12) + 5 


Figure 14-18 shows three ways in which the check box at the bottom of the dialog box 
is dependent on the upper check box’and radio buttons. 


(C] Check Me @ button 1 
O button 2 
O button 3 


C) Depends on bax abave and butians | & 3 


{Check Me © button I 
O button 2 
@ button 3 


(0 Depends on box above and buttons 1 & 3 


{] Check Ma © button 1 
@®@ button 2 
© button 3 


CJ Depends on box ahove and buftans € 3 


Figure 14-18 
Dependencies on radio buttons 


Here is the resource description code describing the operation of the dialog box in 
Figure 14-18: 


notDependent { }, CheckOption { 
NotSet, (15, 15, 31, 100}, "Check Me", "-root", "" 
}, ; 
And { (1, 3} }, CheckOption { 

NotSet, (65, 15, 81, 450}, "Depends on box above and 


buttons 1 & 3", "-abovel", "" 

}, 

Or { ¢ (1 << 12) + 4, (3<< 12) + 4 } }, Dummy ( 

}, 

notDependent { }, RadioButtons { { 
{15, 150, 31, 450}, “button 1", "=-b1", NotSet, “no help", 
{30, 150, 46, 450}, “button 2", "=b2", NotSet, "no help", 
{45, 150, 61, 450}, “button 3", "=b3", NotSet, "no help", 


} }, 


In Figure 14-18 the first CheckOption is Item #1 in the resource description file and 
the next CheckOption is Item #2 in the same file. The third item is a dummy item 
used to perform the complex dependency. Item #4 is the entire cluster of three radio 
buttons. Item #2 (the bottom check box in the sample dialog) is dependent on Item 
#1 (the top check box) AND radio button #1 OR radio button #3. 
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Nested dialog boxes 


Complex tools may require more than one dialog box in order to display all the 
options. When there are several nested dialog boxes, all of them are called from 
buttons in the first dialog box. It’s best to avoid calling nested dialog boxes from 
other nested dialog boxes. 


Figure 14-19 shows how dialog box #2 can be called from dialog box #1. 


wide array itemArray { 
int notDependent = 0; /* item dependent upon */ 
switch { 
case NestedDialog: 
key byte = NestedDialogID; 
byte; /* the number of the dialog 


to call. It must be greater 
than the current dialog */ 


rect; /* bounds of button */ 
estring; /* button's title */ 
Dialog #1 calls dialog #2. estring; /* help text for button */ 


resource 'CMDO' (128) { 
{ 
270, 


we ot 
, 


{ 
notDependent {}, NestedDialog { 
2, 
{135, 357, 155, 468}, 
"Nested Dialog..", 
"This is the help message displayed when the nested dialog button is clicked." 


Dialog|#1 


Figure 14-19 
setting up nested dialog boxes 


Nested dialog boxes 14-2] 


Figure 14-20 shows the recommended placement of nested dialog call buttons. 


Teast Options 
User Interface 
recommends 
that nested 
dialog buttons 
begin at the 
lower-right 
and go up. 


Command Line 
te While the mouse 
is held down 
over any control, 
help info is 


displayed here. 


Help 
This is the help message displayed when the nested dialog button is clicked. 


Figure 14-20 
Placement of nested dialog buttons 


Clicking the Cancel button in a nested dialog box reverts all its controls to their state 
before the nested dialog box was opened, returning the user to dialog box #1. 
Clicking the Do It button (typically labeled “Continue”) saves the current state of all 
controls in the nested dialog box, returning the user to the first dialog box. 


Redirection 


Redirection is the easiest control to add to a Commando resource description file. 
Simply specify the type of redirection and the point location of the upper-left 
corner. Commando takes care of the rest. Here is the case declaration for 
redirection: 


case Redirection 
key byte = RedirectionID; 


byte StandardOutput, /* the type of redirection */ 
DiagnosticOutput, 
StandardInput; 
point; /* upper-left point of the entire contraption */ 
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Figure 14-21 shows the resource code for redirection along with its results. 


notDependent ({}, Redirection { 
StandardInput, 
{15, 27} 

} e 

notDependent {}, Redirection { 


StandardOutput, 
{15, 252} 
}, 


Input Output 


Click here and 
get this pop-up 


/ No Cutpul Rediraction 
New File... 

Existing File... 
Window... 

Current Selection in Window... 
Current Selection in Target Window 
Standard Output 

Standard Diagnostic 

Null Device 
Console Device 


\/ Ne /npul Redirection 
Existing File... 
Window... 

Current Selection in Window... 
Current Selection in Target Window 
Standard Input 

Null Device 
Console Device 


Figure 14-21 
How to obtain input and output redirection 


Files and directories 


There are four types of Commando dialogs, offering four different ways to make files 
and directories available: 


Q as individual items for both input and ouput 
Q as multiple files for input only 

O as multiple files and directories for input only 
O as multiple new files for output 


Individual files and directories 


The Files control enables users to select a single file or directory that can be used for 
input or output. This control supports seven combinations of files, as illustrated in 
Figure 14-22. 
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case Files: 

key byte =~ FilesID: 

byte/[InputFile, 
InputFileOrDir, 
InputOroutputFile, 
InputOroutputOrDir, 


OutputFile, 
OutputFileOrDir, 


These types require the 
‘Additional’ case below. 


These types require the 
‘NoMore’ case below. 


estring; 
byte dim, dontDim: 


This first item is used to select a default file or to 
select no file. The second (and third) item(s) are used 
rect: /* pounds of display box */ 
estring; /* title */ 
another Files item, an extension 
can be specified here to be added 
dimmed if the parent is disabled, 
if this field is "dontDim", then 
Most 
InputOroutputOrDir require three strings. If a string is set to "", 
Commando will use a built-in default. */ 


to select input or output files. */ This case generates 
Go popup. 
estring: /* default file */ 
to the dependents file. */ 
this item won't be dimmed */ 
estring; 


case OptionalFile: 
/* Using this case makes a popup with two or three items. 
key int = 0; 7 
rect; /* bounds of title */ 
estring: /* option to return before file */ 
estring; /* Tf this item is dependent upon 
help text for popup */ 
Normally, dependent items are 
/* These next three strings are the strings displayed in the popup. 
of the file types have only two strings but InputOrOutputFile and 
estring: 
estring: 


Each group of files uses its own case 


/* popup item #1 */ 
/* popup item #2 */ 
/* popup item ¢3 */ 


case RequiredFile: 


/* Using this case makes a button that goes directly to standard 


file. Use this case when a file is required and the user doesn't 
key int = 1; 

rect; /* pounds of button */ 

estring: /* option to return before file */ 
estring: /* help text for button */ 


have the choice of a default file or no file. */ _ 
This case generates 
@ button. 
estring: /* title of button */ 
HS 


/* Some file types take additional information. See the comment next to the 
file types to find out which case to choose here. */ 
switch ( 
case Additional: 
key byte ~ 0; 
estring: /* For InputOrOutputFile, an option 
can be specified when a new 
{or output) file is chosen. */ 
estring FilterTypes =< ":";/* preferred file extension (i.e. ".c") 
If null, no radio buttons will be 
displayed. If FilterTypes is used, 
the radio buttons will toggle 
between showing files only with 
the types below and all files */ 
cstring: /* title of only files button */ 
estring: /* title of all files button */ 
byte = $S$CountOf (TypesArray):/* up to 4 types may be specified */ 
align word; 
array TypesArray ( 
literal longint text = ‘TEXT’, 
obj - ‘OBJ ', 
appl = 'APPL', 
da = 'DFIL', 
tool = 'MPST'; 


/* desired input file type, specify */ 
/* no type for all types */ 


case NoMore: 
key byte = 1; 
de: 


Figure 14-22 
Resource description for “individual files and directories” controls 
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Here is the resource code for the “individual files and directories” 
appear in Figure 14-23. 


notDependent {} , Files { 

InputFile, 

OptionalFile { 
{20,20,40,130}, 
{20,100,40,300}, 

"C Input Files", 

“ a sk A Lh) i 

"Help message here.", 

dim, 

“Read Standard Input", 
"Select a file to compile..", 
te 

}, 

Additional { 
wee 
"Only files that end in .c", 
"All text files", 
{text} 

}, 

}, 
Or {{1}}, Files { 

OutputFile, 

OptionalFile { 
{50,20,70,100}, 
{50,100,70,300}, 
“Object File", 


Novo", Weg, wo", 
"Help message here.", 
dontDim, 


"Send object code to c.o", 
“Select an object file..", 
}, 
NoMore ({}, 


}, 


controls that 


Files and directories 
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Figure 14-23 shows the control resulting from the resource code above. The control is 
shown first in its default state, then as the user selects an input file, and finally as 
Commando produces the object file associated with the input file selected by the 
user, 


Default state 


Choose an input file 


C Input File |vRead Standard Input | 


Select a file to compile... 


Object File [od 


Object file dependent on Input 


C input File jhd:...:;Commando:checkBou.c 
Object File 


Figure 14-23 
Examples of “Individual files and directories” controls 


Multiple files and directories for input and output 


Use the case MultiFiles (shown here) to enable users to select multiple files and 
directories for input and output Note the four cases representing subtypes within the 
case MultiFiles: 


O case MultiInputFiles 

O case MultiDirs 

QO case MultiInputFilesAndDirs 
O case MultiOutputFiles 
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Here is the MultiFiles case: 


case MultiFiles: 
key byte = MultiFilesID; 
estring; 
cstring; 
align word; 
rect; 
cstring; 


case MultiInputFiles: 
key byte = 0; 


byte = $$CountOf (MultiTypesArray) ; 


align word; 
array MultiTypesArray { 


literal longinit text = 'TEXT', 


obj = 'OBJ', 
appl = 'APPL', 
da = 'DFIL', 


tool = 
‘e 
estring FilterTypes = ":"; 
estring; 
estring; 


case MultiDirs: 
key byte = 1; 


case MultiInputFilesAndDirs: 


key byte = 2; 


case MultiOutputFiles: 
key byte = 3; 
}; 


/* 


/* 


/* 


/* 


/* title of only files button */ 
title of all files button */ 


/* 


button title */ 
help text for button */ 


bounds of button */ 
message like "Source files 
to compile:" */ switch { 


up to 4 types may be 
specified */ 


desired input file 
type, specify no type */ 
for all types */ 


preferred file extension 
(that is, ".c"). If null, 
no radio buttons will be 
displayed. If FilterTypes 
is used, the radio buttons 
will toggle between show- 


ing files with only the types 


below, and all files. */ 


Figure 14-24 is a Files dialog box controlled by resource code using the MultiFiles 


case. Here is the resource code: 


notDependent {}, MultiFiles { 


"Description Files..", 


"Select resource input files to compile", 


{60, 330, 80, 468}, 


“Resource Description Files:", 


MultiInputFiles ({ 
{text}. 
bars) ar 
“Piles ending in .r", 
"All text files" 
}, 
be 
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"Description Files..." is the button in the Rez dialog box that displays the large 
standard file dialog box shown in Figure 14-24. The last two titles refer to the two 
radio buttons. 


€3 PExamples 


QO Memory.r 
Q ResEqual.r 


DO Sample.r 


@ Only files endingin.r QO All text files 
Resource Description Files: 


:PExamples:Memory.r >} 


:PEXamples:ResEqual.r 


Remove 


rm 
Vv) 


Figure 14-24 
Example of multiple Input files 


In the above example two resource files have just been added. 


Multiple files and directories for input only 


Here’s how you can use the case MultiFiles to enable the user to select multiple 
directories for input only. 


NotDependent {}, MultiFiles { 
"Include Paths...", 
“Help message for directory button.", 
{110, 330, 130, 468}, 
“Include Search Paths:", 
Wag) 


MultiDirs {}, 
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The first item in the above code, "Include Paths...", is the button in a frontmost 
dialog box (in this example Rez was used) that generates the file dialog box shown in 
Figure 14-25. "Include Search Paths :" is the title of the scrollable window at the 
bottom of the dialog box. Two Includes folders have just been selected from the 


upper window and added to the Include Search Paths window just below. 


Add Current Directory: 


© AExamples KY 
| 


C Aincludes 
© Applications 
© AStructMacs 
© CExamples 
© Cincludes 
© CLibraries 
© Examples 

© Libraries 


Include Search Paths: 


:‘Rincludes: 


:Alnciudes: 


Remove 


Figure 14-25 
Multiple directories for input 


Another file dialog box is used to select multiple files and directories. This dialog 
box appears in Figure 14-26. Here is the resource code that produces this dialog box. 


NotDependent {}, MultiFiles { 
"Files to duplicate..", 
"This button brings up a dialog allowing" 
"selection of files and directories to duplicate.", 
{25, 50, 45, 230}, 
“Piles and Directories to duplicate:", 


we 
, 


MultiInputFilesAndDirs {} 


Add Current Directory: 
@& MPW 


© Rincludes 
© ROM Maps 
© Scripts 

QO Startup 

D Suspend 

QO Sys€rrs.£rr 
© Tools 

QO UserStartup 
QO Worksheet. 


Worksheet fldd » | 


Figure 14-26 
Example of a “directories” control for multiple input files 
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Multiple new files 
The case MultiFiles also gives the user the ability to select multiple files for output. 
Here is the resource code resulting in the example shown in Figure 14-27. 


notDependent { }, MultiFiles { 
"New Files...", 
"Help message for button", 
{110, 330, 130, 468}, 
"New files to open:", 
Want, 


MultiOutputFiles { }, 


 AExamples 
@ Alnciudes 
© Applications 
© AStrucMacs 
© CExamples 
© Cincludes 


New files to open: 


stestfilel 
stestfile2 
hd:MPW:DifferentDirFile 


Figure 14-27 
Using the MultiOutpufFiles subcase of the case MulftiFiles 


A Commando example 


The best way to learn how to make a Commando interface is to study an actual 
Commando resource for an existing MPW tool. Choose a tool, explore the 
operation of the controls in its Commando dialog, and then use DeRez to generate a 
readable version the tool’s Cmdo.r resource. 


To obtain the Commando resource for a tool, use this syntax: 
DeRez {MPW}Tools: toolname Cmdo.r -only cmdo 
To obtain the Commando resource for a Shell command, use this syntax: 


DeRez {MPW}"MPW Shell" Cmdo.r -only "'cmdo' (d"commandname 9") " 
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For your convenience, the Commando resource for ResEqual, ResEqual.r, is shown 
here. You can find this file in the PExamples folder. 


#include "cmdo.r" 


resource ‘'cmdo' 


{ 


240, 
“ResEqual compares the resources in two files and reports the 


{ 


(355) { 


NotDependent {}, Files { 
InputFile, 
RequiredFile { 
{40, 40, 60, 190}, 
"Resource File 1", 
"Select the first file to compare.", 
} c 
Additional { 
wat 
FilterTypes, 
"Only applications, DA’s, and tools", 
“All files", 
{ 
appl, 
tool, 
da 


}, 
Or {{1}}, Files { 
InputFile, 
RequiredFile ( 
{70, 40, 90, 190}, 
“Resource File 2", 
"Select the second file to compare.", 
}, 
Additional ({ 


te 
, 


FilterTypes, 
"Only applications, DA’s, and tools", 
"All files", 
{ 
appl, 
tool, 
da 


}, 

NotDependent (}, TextBox { 
gray, 
{30, 35, 95, 195}, 
"Files to Compare" 

* 

NotDependent {}, CheckOption { 
NotSet, 
{105, 75, 121, 155}, 
"Progress", 
Ham, 
“Write progress information to diagnostic output." 


A Commando example 


differences.", 
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NotDependent {}, Redirection { 
StandardOutput, 
{40, 300} 

}, 

NotDependent {}, Redirection { 
DiagnosticOutput, 
{80, 300} 

}e 

NotDependent {}, TextBox { 
gray, 
{30, 295, 121, 420}, 
"Redirection" 

}, 

Or ({2}}, DoItButton { 

}, 


3 


The above resource code generates the frontmost dialog box of ResEqual, which 
appears in Figure 14-28. 


Resequal Options 


(= to Compare———, setae 


|(tescuree rieT —) foutout____ 


C) Progress 


Command Line 
eee | 


Help 
Resfqual compares the resources in two files and reports the differences. 


| Citesource Fie 2 == | 


Figure 14-28 
A Commando example: frontmost ResEqual dialog box 
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Chapter 15 


Writing a Desk Accessory 
or Other Driver Resource 


This chapter documents the DRVRRuntime library and describes the specifics of 
writing a desk accessory or other driver by using MPW and MPW Pascal or MPW C. 
The material in this chapter is specific to the MPW programming languages. Because 
a desk accessory is a special case of a driver, all of the information in this chapter 
applies to both. You should already be familiar with the following: 


O “Writing Your Own Desk Accessories” in the Desk Manager chapter of Inside 
Macintosh 


O The Device Manager chapter of Inside Macintosh (for information about 'DRVR' 
resources, and so on) 


O “Building a Desk Accessory or Driver” in Chapter 9 of this reference 


For information about the actual routines used in Pascal, C, or assembly language, 
see the appropriate MPW language reference manual. 


The DRVRRuntime library 


Desk accessories have traditionally been written in assembly language, partly 
because of the peculiar 'DRVR' resource format used for desk accessories. Setting up 
the 'DRVR' layout header, passing register-based procedure parameters, and coping 
with the nonstandard exit conventions of the driver routines have made it difficult to 
implement desk accessories in higher-level languages. To overcome these difficulties 
and simplify the task of writing a desk accessory in Pascal or C, MPW provides the 
following: 


O The library DRVRRuntime.o, which contains the “glue” for setting up your open, 
prime, status, control, and close routines 


QO The resource type 'DRVW', declared in {RIncludes!}MPWTypes.r. The 'DRVW' 
resource is an intermediate form of the 'DRVR' resource, and contains constants 
that point to the addresses of the driver routines in DRVRRuntime.o 


The DRVRRuntime library contains a main entry point that overrides the main entry 
point in CRuntime.o or in your Pascal or assembly-language source. The 
DRVRRuntime entry point contains driver glue that sets up the parameters for you, 
calls your routines, and performs the special exit procedure required for a desk 
accessory to return control to the system. Your routines perform the actions of the 
desk accessory, such as opening a window and responding to mouse clicks in it. 


The Resource Compiler input (resource description file) for your desk accessory 
includes the details of your desk accessory header, such as its driver flags, event 
mask, menu ID, and driver name. The driver is built by coercing the intermediate 
'DRVW' resource to a resource of type 'DRVR', which is the format required for desk 
accessories. Your resource description file also specifies resources for strings, 
windows, and menus, if used in your desk accessory. (For an example of such a 
resource description file, see “The Desk Accessory Resource File” in Chapter 9.) 


Using DRVRRuntime.o has several advantages: 
© No assembly-language source code is required. 


Q The Resource Compiler is an integral step in the build process, permitting the easy 
addition of a desk accessory menu or other owned resources. 


QO The programmer’s interface to the open, prime, status, control, and close routines 
uses standard calling conventions. Each function returns a result code which is 
passed back to the system. 
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CG The DRVRRuntime glue handles the proper exit conventions. (Drivers have 
peculiar exit conventions, requiring immediate calls to exit via an RTS instruction, 
but non-immediate calls to jump to the IODone routine—these exit procedures 
cannot be expressed in C or Pascal.) 


Together, the DRVRRuntime library and the 'DRVW' resource form the dispatch 
mechanism to your driver routines. The next section describes the structure of your 
driver routines. 


What your routines need to do 


To write a driver, you need to write five functions named DRVROpen, DRVRPrime, 
DRVRStatus, DRVRControl, and DRVRClose. 


“* Pascal note: In Pascal, you'll need to write a unit that declares these five 
functions in your interface. 


Each of these functions is declared to use Pascal calling conventions, so that the 
DRVRRuntime library is available for use by both C and Pascal programmers. (See 
the appropriate language reference manual for details.) 


The calling sequence for all five driver routines is the same: The parameter ioPB is 
the pointer to the driver’s I/O parameter block (passed from the system in register 
AO), and dCt1 is the pointer to the driver’s device control entry (from register A1). 
The function returns a result code, which DRVRRuntime puts in register DO. This 
result code is a Pascal integer (C short). Desk accessories always return a result code 
of 0. 


For example, here is the Pascal declaration for your DRVROpen routine: 
FUNCTION DRVROpen(ct1PB: ParmBlkPtr; dCTl: DCtlPtr): OSErr; 


Types ParmBlkPtr and DCuPtr are declared in the file OSIntf.p. Type OSErr is an 
INTEGER, and is also defined in OSIntf.p. 


In C, you would need to write the routines as follows: 


pascal OSErr 

DRVROpen (ct 1PB,dCtl) 
CntrlParam *ct1PB; 
DctlPtr dctl; 


return (resultCode) ; 
} 


Types CntrlParam and DCuPtr are declared in the file Devices.h. Type OSErr is a 
short, and is defined in Types.h. 


“ Desk accessories only: The body of the desk accessory code will reside in your 
routines DRVROpen, DRVRControl, and DRVRClose. Your routines DRVRPrime 
and DRVRStatus are never called by the system, but the DRVRRuntime library 
expects them to be present anyway—they cannot be omitted. It is sufficient to 
declare them and have them simply return 0. 


What your routines need to do 
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Programming hints 


In the current release of MPW, global data is not available for use by desk 
accessories. That is, variables declared outside your functions cannot be used. In 
particular, the following language constructs reference the global data area and 
cannot be used: 


Asm DATA directives 
Pascal UNIT variables 
C static or extern variables; string constants 


Also note that QuickDraw globals cannot be used directly. Further, you cannot call 
library functions that use any of these things. (Look for the Linker message “No global 
data was allocated.”) 


** Note: Apple is investigating the use of A5-based global variables in desk 
accessories. Currently several Macintosh applications contain trap-override or 
ROM hook routines that expect A5 to point to the application’s globals, but 
without saving, setting, and restoring A5 to ensure that this is the case. Such 
applications are incompatible with desk accessories that use A5, because the desk 
accessory’s calls to the ROM could end up in the application’s trap-override or 
hook code. 


Typically, C and Pascal programmers will allocate global storage from the heap and 
use 'STR#! resources for string constants. If you need to allocate global data from the 
heap, you can declare a record containing all of the global variables you need. In 
your DRVROpen routine, you should allocate memory from the heap with the size of 
this record, and store its handle in the dCtStorage field of the device control entry. 
Then, to reference an element in the record, you can use this handle to reference the 
global variable that you want to use. 


Sample desk accessory 


A sample desk accessory, Memory, is included in the Examples folders for assembly 
language, C, and Pascal. This desk accessory has the following features: 


Q It displays the current amount of free space in both the application heap and the 
system heap. 


C It displays the number of free bytes on the default volume, along with the name of 
the default volume. 


Q It performs these operations every five seconds, so that you can see how your 
memory conditions change. 


For instructions on building this desk accessory, see the Instructions file in the 
Examples folder, or refer to “Building a Desk Accessory or Driver” in Chapter 9. 
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Appendix A 


Macintosh Workshop 
Files 


This appendix lists all of the files provided with the Macintosh Programmer's 
Workshop 2.0.2, including MPW Pascal and MPW C. A list of MPW files as they are 
distributed on 800K disks appears below; a list of the files in their standard 
configuration on a hard disk begins on page A-7. (Volume names are shown in bold; 
directory names begin and end with a colon.) 


Distribution files 


Distribution disk MPW1: 


Files 
MacsBug 
'MPW Shell’ 
MPW.Help 
Quit 
Resume 
Startup 
Suspend 
SysErrs.Err 
UserStartup 
Worksheet 


MPW1:Applications: 
ResEdit 


MPW1:Examples: 
AddMenus 
Instructions 
Lookup 

‘Startup, etc.’ 

State 

‘Unix Aliases' 


MPW1:Libraries: 
DRVRRuntime.o 
Interface.o 
ObjLib.o 
PexformLib.o 
Runtime.o 

SERD 
ToolLibs.o 


MPW1:RIncludes: 
Cmdo.r 
MPWTypes.r 
Size.R 

SysTypes.r 
Types.r 


MPW/1:Scripts: 
BuildCommands 
BuildMenu 
BuildProgram 
CreateMake 
DirectoryMenu 
Line 
SetDirectory 


Distribution disk MPW2: 


MPW?2:Tools: 
Canon 
Commando 
Count 
CVTObj 
DeRez 
DumpCode 
DumpObj 
GetListItem 
Lib 

Link 

Make 
PerformReport 
Print 
ResEqual 

Rez 

RezDet 
Search 
Translate 
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Distribution disk MPW3: 


'MPW3:More Tools:' 
Backup 
Canon. Dict 
Compare 
Entab 

FileDiv 
GetErrorText 
GetFileName 
MakeErrorFile 
ProcNames 
SetVersion 


‘MPW3:ROM Maps:' 
MaclIIROM.map 
MacPlusROM.map 
MacSEROM.map 


MPW Assembler files 


Distribution disk MPW Assembler]: 


'MPW Assembler1' 
Asm 

MDSCvt 

MDSCvt. Directives 
TLACvt 

TLACvt. Directives 


Distribution disk MPW Assembler2: 


'MPW Assembler2:AExamples:' 
Count.a 

Count.r 

Instructions 

MakeFile 

Memory.a 

Sample.a 

Sample.r 

Stubs.a 


'MPW Assembler2:AlIncludes:' 
App!DeskBus.a 

Atalkequ.a 

FixMath.a 

FSEqu.a 

FSPrivate.a 

Graf3DEqu.a 

HardwareEqu.a 

IntEnv.a 


MPW Assembler files 
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ObjMacros.a 
PackMacs.a 
PaletteEqu.a 
PickerEqu.a 
PrEqu.a 
PrintCallsEqu.a | 
PrintTrapsEqu.a 
Private.a 
QuickEqu.a 
ROMEqu.a 
SANEMacs.a 
ScriptEqu.a 
SCSIEqu.a 
ShutDownEqu.a 
Signal.a 
SlotEqu.a 
SonyEqu.a 
Sound.a 
SysEqu.a 
SysErr.a 
TimeEqu.a 
ToolEqu.a 
Traps.a 
VideoEqu.a 


'MPW Assembler2:AStructMacs:' 
FlowCtlMacs.a 

ProgStrucMacs.a 

Sample.a 


MPW Pascal files 
Pascal 
PasMat 
PasRef 


'MPW Pascal:'PExam ples: 
Instructions 
MakeFile 
Memory.p 
Memory.r 
ResEd.p 
ResEd68K.a 
ResEqual.p 
ResEqual.r 
ResXXXXEd.p 
Sample.p 
Sample.r 
Stubs.a 
TestPerf.p 
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'MPW Pascal:'PInterfaces: 


AppleTalk.p 
CursorCtl.p 
ErrMgr.p 
FixMath.p 
Graf3D.p 
IntEnv.p 
MacPrint.p 
MemTypes.p 
Objintf.p 
OSIntf.p 
Packintf.p 
PaletteMgr.p 
PasLibIntf.p 
Perf.p 
PickerIntf.p 
PrintTraps.p 
Quickdraw.p 
ROMDefs.p 
SANE.p 
Script.p 
SCSIIntf.p 
Signal.p 
Sound.p 
Toolintf. p 
VideoIntf.p 


'MPW Pascal:'PLibraries: 
PasLib.o 

SANELib.o 

SANELib881.0 


MPW C files 


C 


'MPW C:'CExamples: 
Count.c 
Count.r 
Instructions 
MakeFile 
Memory.c 
Memory.r 
Sample.c 
Sample.r 
Stubs.c 
TestPerf.c 


MPW C files 
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'MPW C:'CIncludes: 
AppleTalk.h 
Controls.h 
CType.h 
CursorCtl.h 
Desk.h 
DeskBus.h 
Devices.h 
Dialogs.h 
DiskInit.h 
Disks.h 
ErrorMgr.h 
ErrNo.h 
Errors.h 
Events.h 
FCantl.h 
Files.h 
FixMath.h 
Fonts.h 
Graf3D.h 
1OCtu.h 
Lists.h 
Math.h 
Memory.h 
Menus.h 
OSEvents.h 
OSUtils.h 
Packages.h 
Palette.h 
Perf.h 
Picker.h 
Printing.h 
PrintTraps.h 
Quickdraw.h 
Resources.h 
Retrace.h 
ROMDefs.h 
SANE.h 
Scrap.h 
Script.h 
SCSI.h 
SegLoad.h 
Serial.h 
SetJmp.h 
ShutDown.h 
Signal.h 
Slots.h 
Sound.h 
Start.h 
StdlO.h 
String.h 
Strings.h 
TextEdit.h 
Time.h 
ToolUtils.h 
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Traps.h 
Types.h 
Values.h 
VarArgs.h 
Video.h 
Windows.h 


'MPW C:'CLibraries: 
CInterface.o 
CLib881.0 
CRuntime.o 
CSANELib.o 
CSANELib881.0 
Math.o 

Math881.o0 

StdCLib.o 


Hard disk configuration 


HardDisk:MPW: 
:AExamples: 
:AIncludes: 
:Applications: 
:AStructMacs: 
:CExamples: 
:CIncludes: 
:CLibraries: 
:Examples: 
:Libraries: 
:PExamples: 
:PInterfaces: 
:PLibraries: 
:RIncludes: 
"ROM Maps:' 
:Scripts: 
:Tools: 
MacsBug 
'MP'W Shell! 
MPW.Help 
Quit 

Resume 
Startup 
Suspend 
SysErrs.Err 
UserStartup 
Worksheet 


HardDisk:MPW:AExam ples: 
Count.a 

Count.r 

Instructions 

MakeFile 

Memory.a 

Sample.a 

Sample.r 

Stubs.a 
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HardDisk:MPW:AlIncludes: 
App|DeskBus.a 
ATalkEqu.a 
FixMath.a 
FSEqu.a 
FSPrivate.a 
Graf3DEqu.a 
HardwareEqu.a 
IntEnv.a 
ObjMacros.a 
PackMacs.a 
PaletteEqu.a 
PickerEqu.a 
PrEqu.a 
PrintCallsEqu.a 
PrintTrapsEqu.a 
Private.a 
QuickEqu.a 
ROMEqu.a 
SANEMacs.a 
ScriptEqu.a 
SCSIEqu.a 
ShutDownEqu.a 
Signal.a 
SlotEqu.a 
SonyEqu.a 
Sound.a 
SysEqu.a 
SysErr.a 
TimeEqu.a 
ToolEqu.a 
Traps.a 
VideoEqu.a 


HardDisk:MPW:Applications: 
ResEdit 


HardDisk:MPW:AStructMacs: 
FlowCtlMacs.a 
ProgStrucMacs.a 

Sample.a 


HardDisk:MPW:CExamples: 
Count.c 
Count.r 
Instructions 
MakeFile 
Memory.c 
Memory.r 
Sample.c 
Sample.r 
Stubs.c 
TestPerf.c 


A-8 Appendix A: Macintosh Workshop Files 


HardDisk:MPW:ClIncludes: 


AppleTalk.h 
Controls.h 
CType.h 
CursorCtl.h 
Desk.h 
DeskBus.h 
Devices.h 
Dialogs.h 
DiskInit.h 
Disks.h 
ErrMgr.h 
ErrNo.h 
Errors.h 
Events.h 
FCntl.h 
Files.h 
FixMath.h 
Fonts.h 
Graf3D.h 
TOCtl.h 
Lists.h 
Math.h 
Memory.h 
Menus.h 
OSEvents.h 
OSuUtils.h 
Packages.h 
Palette.h 
Perf.h 
Picker.h 
Printing.h 
PrintTraps.h 
Quickdraw.h 
Resources.h 
Retrace.h 
ROMDefs.h 
SANE.h 
Scrap.h 
Script.h 
SCSI.h 
SegLoad.h 
Serial.h 
SetJmp.h 
ShutDown.h 
Signal.h 
Slots.h 
Sound.h 
Start.h 
StdIO.h 
String.h 
Strings.h 
TextEdit.h 
Time.h 
ToolUtils.h 
Traps.h 


Hard disk configuration 
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Types.h 
Values.h 
VarArgs.h 
Video.h 
Windows.h 


HardDisk:MPW:CLibraries: 
CInterface.o 

CLib881.0 

CRuntime.o 

CSANELIib.o 
CSANELib881.0 

Math.o 

Math881.0 

StdCLib.o 


HardDisk:MPW:Exam ples: 
AddMenus 

Instructions 

Lookup 

‘Startup, etc. 

State 

'Unix Aliases' 


_HardDisk:MPW:Libraries: 
DRVRRuntime.o 
Interface.o 

ObjLib.o 

PerformLib.o 

Runtime.o 

SERD 

ToolLibs.o 


HardDisk:MPW:PExamples: 
Instructions 
MakeFile 
Memory. p 
Memory.r 
ResEd.p 
ResEd68K.a 
ResEqual.p 
ResEqual.r 
ResXXXXEd.p 
Sample.p 
Sample.r 
Stubs.a 
TestPerf.p 


A-10 Appendix A: Macintosh Workshop Files 


HardDisk:MPW:PiInterfaces: 


AppleTalk.p 
CursorCtl.p 
ErrMgr.p 
FixMath.p 
Graf3D.p 
IntEnv.p 
MacPrint.p 
MemTypes.p 
Objintf.p 
OSIntf.p 
PackIntf.p 
PaletteMgr.p 
PasLibIntf.p 
Perf.p 
PickerIntf.p 
PrintTraps.p 
Quickdraw.p 
ROMDefs.p 
SANE.p 
Scripl.p 
SCSIIntf.p 
Signal.p 
Sound.p 
Toolintf.p 
VideoIntf.p 


HardDisk:MPW:PLibraries: 
PasLib.o 

SANELib.o 

SANELib881.0 


HardDisk:MPW:RIncludes: 
Cmdo.r 

MPWTypes.r 

Size.R 

SysTypes.r 

Types.r 


HardDisk:MPW':ROM Maps:' 
MacIIROM.map 
MacPlusROM.map 
MacSEROM.map 


HardDisk:MPW:Scripts: 
BuildCommands 
BuildMenu 
BuildProgram 
CreateMake 
DirectoryMenu 

Line 

SetDirectory 
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HardDisk:MPW:Tools: 
Asm 

Backup 

Cc 

Canon 

Canon. Dict 
Commando 
Compare 
Count 

CVTObj 

DeRez 
DumpCode 
DumpObj 
Entab 

FileDiv 
GetErrorText 
GetFileName 
GetListItem 

Lib 

Link 

Make 
MakeErrorFile 
MDSCvt 
MDSCvt. Directives 
Pascal 

PasMat 

PasRef 
PerformReport 
Print 
ProcNames 
ResEqual 

Rez 

RezDet 

Search 
SetVersion 
TLACvt 
TLACvt. Directives 
Translate 
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Appendix B 


Summary of Selections 
and Regular Expressions 


This appendix formally defines the syntax of selections and regular expressions as 
used in the Shell command language. It also lists the Option-key characters used in 
selections and regular expressions. For examples of their use, see Chapter 6. 


Selections 


Selections are passed as arguments to the editing commands. They’re defined in 
Table B-1. 


Table B-1 
Selections 


selection (specifies a selection or insertion point) 


§ Current selection 

name Identifies marked text 

number Line number 

! number number lines after the end of the current selection 

j number number lines before the start of the current selection 

position Position (defined below) 

pattern Pattern (defined below) 

(selection) Selection grouping 

selection : selection Both selections and everything in between 

position (specifies an insertion point) 

° Position before the first character in the file 

00 Position after the last character in the file 

A selection Position before the first character of selection 

selection A Position after the last character of selection 

selection ! number Position mumber characters after the end of selection 

selection ; number Position number characters before the beginning of 
selection 


pattern (specifies characters to be matched) 
/ entireRegularExpr/ Regular expression—search forward (see Table B-2) 
\ entireRegularExpr\ Regular expression—search backward 


B-] 


This is the precedence of the selection operators, from highest to lowest: 


/ and \ 
C) 
A 
land} 


Regular expressions 


Regular expressions are used for pattern matching within /.../ and \...\. (ee 
“pattern” in Table B-1.) Regular expressions are defined in Table B-2. 


Table B-2 
Regular expressions 


entireRegularExpr 

© regularExpr 
regularExpr co 
regularExpr 

regularExpr 

simpleExpr 
taggedExpr 

literal 

regularExpr, regularExpr, 
simpleExpr 
(regularExpr) 
characterExpr 
simpleExpr* 
simpleExpr + 
simpleExpr «number» 
simpleExpr «number,» 
simpleExpr « n,, nm» 


taggedExpr 
CregularExpr)® digit 


literal 
‘string’ 
"string" ; 


characterExpr 
character 


Ocharacter 


2 


= 


{ characterList ] 
[- characterList ] 
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Regular expression at beginning of line 
Regular expression at end of line 
Regular expression 


Untagged regular expression 

Tagged regular expression 

Quoted string literal 

regularExpr, followed by regularExpr, 


Regular expression grouping 

Single-character regular expression 

Regular expression zero or more times 

Regular expression one or more times 

Regular expression number times 

Regular expression at least number times 

Regular expression at least 7, times and at most 7, 
times 


The string matched by the regularExpr can be 
referred to as ®digit 


Each character in string is taken literally 
Each character in string is taken literally, except for a 
and { } substitutions 


Character (unless it’s listed as special following the 
table) 

d defeats special meaning of following character 

Any character except Return 

Any string not containing a Return, including the null 
string (this is the same as ?*) 

Any character in the list 

Any character not in the list 
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Table B-2 (continued) 
Regular expressions 


characterList 

] “]” first in list represents itself 

- “—” first in list represents itself 

character Character 

characterList character List of characters 

character, — character, Character range from character, to character, 
inclusive 


Note: The regular expression operators ?, », [...], *, +, and «...» are also used in filename 
generation. 


The following characters have special meanings: 


7) Always special, except within '...' 

?= *+([«()'" Special everywhere except within [...],'...') and "..." 
® Special only after a right parenthesis character, ) 

e Special as first character of entire regular expression 
oo Special as last character of entire regular expression 
/ \ Special if used to delimit regular expression 

{ } Special everywhere except within '...' 

The operators are listed below beginning with the highest-precedence operators. 
€ ) 

2? = * + [] «» ® 

concatenation 


Option-key characters 


The following Option-key characters are used in selections and regular expressions. 


Character Key Meaning 

§ Option-6 Current selection character 

) Option-d Escape character 

= Option-x Any string 

° Option-8 Beginning of line or file 

oo Option-5 End of line or file 

i Option-1 Minus number of lines or spaces 
A Option-j Position 

® Option-r Tag operator 

« Option-\ Encloses number of repetitions 
» Shift-Option-\_— Encloses number of repetitions 


Option-key characters 
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Appendix C 


MPW Character 
Reference 


This appendix gives a brief summary of the special operators used in the Macintosh 
Programmer’s Workshop. For characters that are part of the extended character set, 
Option-key combinations are also given. For details on the action of these 
operators, see Chapters 5 and 6. 


Table C-1 
MPW operators 


Operator 


Shell characters 
space 
tab 
return 
| 
&E& 


1 | 
(commands) 
# comment 
Ochar 


'chars' 
"chars" 


/chars/ 


Meaning 


Separates words 

Separates words 

Separates commands 

Separates commands 

Pipe—separates commands, piping output to input 
“And”—separates commands, executing second if first 
succeeds 

“Or”—separates commands, executing second if first fails 
Group commands 

Ignore comment 

Escape—literalizes char; dn, dt, and of are special ( is 
Option-D) 

“Hard quotes”—literalize chars 

“Soft quotes”—literalize chavs except for {...} (variable 
substitution), ~...~ (command substitution), and @ (escape) 
Regular expression quotes—literalize /chars/ except for 
(voshi ee and 

Ellipsis (Option-semicolon; not three periods) following a 
command invokes Commando 


(continued) 


Table C-1 (continued) 
MPW operators 


Operator 


Shell characters 
\ chars\ 


{variable} 
~command 
< filename 
> filename 
>> filename 
2 filename 


2> filename 


Meaning 


Regular expression quotes—literalize \chars\ except for 
{...}, *...°, and a | 

Substitute variable 

Substitute output of command 

Redirect standard input 

Redirect standard output, replacing contents of filename 
Redirect standard output, appending to filename 
Redirect diagnostics, replacing contents of filename @ is 
Option->) 
Redirect diagnostics, appending to filename @ is 
Option->) 


Selections (editing commands) 


§ 

n 

In 

i” 

e 

oo 
Aselection 
selectionA 
selection !n 
selection jn 
/regExpr/ 

\ regExpr\ 
selection,:selection 


Current selection (§ is Option-6) 

Line number n 

n lines after § 

n lines before § (j is Option-1) 
Beginning of file Ce is Option-8) 

End of file (ce is Option-5) 

Beginning of selection (A is Option-J) 
End of selection (A is Option-J) 

n characters before selection 

n characters after selection G is Option-1) 
regExpr after current selection 
regExpr before current selection 
selection,, selection, and in between 


Regular expressions (and filename generation) 


char 

dchar 

'char...' 

? 

(characterList] 
[—characterLis¢] 
regExpr* 
regExpr+ 
regExpr«n» 
regExpr«n,» 
regExpr«n,,1» 
CregExpr) 
CregExpn®n 
regExpr, regEXprs 
regExpr 
regExproo 
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Match char 

Literal chard is Option-D) 

Literal chars 

Any character 

Zero or more chars (short for *) (= is Option-X) 

Any character in characterList 

Any character not in characterList (— is Option-L) 
regExpr zero or more times 

regExpr one or more times 

regExpr n times (« and » are Option-\ and Option-Shift-\) 
regExpr n or more times | 
regExpr n, to n, imes 

regExpr (grouping) 

Tagged regExpr, where 0<n<9 (® is Option-R) 

regExpr, followed by regExpr, 

regExpr at beginning of line (¢ is Option-8) 

regExpr at end of line (ce is Option-5) 
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Table C-1 (continued) 


MPW operators 


Operator 


Shell numbers 


Meaning 


Hexadecimal number 
Hexadecimal number 


Shell operators (by precedence) 


$nnn 
Oxnnn 
(expr) 

! NOT -=A 
* 

+ DIV 
% MOD 
+ 

<< 

>> 

< 

<= < 

> 

>= > 

t= <> % 
t a 

& 

A 

| 

&& AND 
I OR 


Expression grouping 

(unary) arithmetic negation 
(unary) bitwise negation 

(unary) logical negation (— is Option-L) 
Multiplication 

Division (+ is Option-/) 

Modulus 

Addition 

Subtraction 

Shift left 

Shift right Cogical) 

Less than 

Less than or equal @ is Option-<) 
Greater than 

Greater than or equal @ is Option->) 
Equal 

Not equal (+ is Option-=) 

Matches regular expression 

Does not match regular expression 
Bitwise AND 

Bitwise XOR 

Bitwise OR 

Logical AND 

Logical OR 


Appendix C: MPW Character Reference 


C-3 


Appendix D 


Resource Description 
Syntax 


This appendix defines the form of a resource description file, used by the Resource 
Compiler and Decompiler. See Chapter 8 for information on how to use these tools. 


syntax notation 


The following syntax notation is used in this appendix: 


terminal Must be entered as shown 

non-terminal May be replaced by anything matching its definition 

AIl|BI|cC Either A or B or C (vertical stacking also indicates an either/or 
choice) 

(6312 Enclosed element is optional, but may not be repeated 

Lett Enclosed element may be repeated one or more times (not 
optional) 

ee aad Enclosed element may be repeated zero or more times 

{...}” Enclosed element must be repeated nm times 


If one of the syntax elements must be included literally, it is shown enclosed in single 
quotes; for example, 


{ ‘(' data-string ‘}' }? 


indicates that a data-string is optional, and must be enclosed in braces, if included. 
Otherwise, all punctuation (; , ' ™ $ =) must be entered as shown. 


Note that the ellipsis (three closely spaced periods) within braces signifies only some 
unspecified element on which an operation is to be performed. An actual ellipsis in a 
command line (Option-semicolon) would invoke a command’s Commando 
dialogs. 


Note that the semicolon is a statement terminator; every statement must be 
terminated by a semicolon. In a resource type definition, semicolons can be 
liberally sprinkled without ill effect. In a resource specification (where the actual 
resource data is initialized), commas are used everywhere to separate items, 
including array elements. 


The nonterminal symbols used are fully defined under “Syntax” at the end of this 
appendix. 


Structure of a resource description file 


The Resource Compiler input file consists of any number of statements, where a 
statement may be any of the following: 


include Include resources from another file. 

read Read the data fork of a file and include it as a resource. 

data Specify raw data. 

type Declare resource type descriptions for subsequent resource 
statements. 

resource Specify data for a resource type declared in a previous type 
statement. 


Include—include resources from another file 


include (file { include-selector }? ; 


include-selector ::= 


file ::= 
ID-specifier ::= 


ID-range ::= 
resource-spectfier ::= 
resource-ID ::= 

resource-name ::= 
resource-attributes ::= 
resource-numeric-attributes ::= 


resource-literal-attributes ::= 


resource-type { ‘(’ ID-specifier ‘)’ }? 
not resource-type 
resource-typel as resource-type2 
resource-typel ‘(’ ID-specifier ‘)’ 
as resource-type2 ‘(’ resource-specifier ‘)’ 


string 


ID-range 
resource-name 


ID {: ID}? 

resource-ID { , resource-name }? { resource-attributes }? 
word-expression 

string 

{resource-literal-attributes }* | resource-numeric-attributes 
,oyte-expression 


{,sysheap | ,appheap }? 
{,purgeable | ,nonpurgeable }? 
{,locked | , unlocked }? 
{,preload | ,nonpreload }? 


Read—read data as a resource 


read vresource-type ‘('resource-specifier ‘)’ file ; 
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Data—specify raw data 


data resource-type ‘('resource-specifier‘)’ ‘{’ data-string{; }2‘}’ ; 


Type—declare resource type 
type resource-type { ‘(’ID-range ‘)’ }? ‘{’ { type-statement ;} * ‘}’ ; 


resource-type ::= long-expression 
type-statement ::= data-type 
ftil-type 
alignment 
Switch-type 
array-type 
Data-type 
data-type ::= data-type-specifier { symbolic-declaration | = declaration-constant }? 
data-type-specifier ::= char 


string { ‘(’ length ‘]’ }? 
pstring {‘(’ length ‘]’ }? 
estring {‘[’ length‘}’}? 
wstring { ‘’ length '} }? 
numeric-type-specifier 
point 

rect 


length ::= expression 


numeric-type-specifier ::= boolean 
{ unsigned }? { radix}? numeric-type 


radix ::= binary 
octal 
decimal 
hex 
literal 


numeric-type ::= byte 

integer 

longint 

bitstring ‘[’ length ‘}’ 
symbolic-declaration ::= range-block { , range-block }* 
range-block ::= identifier { = declaration-constant }? 


declaration-constant ::= expression 
point-constant 
rect-constant 
String 
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Fill-type 


fill-type ::= fill fill-size {‘[' expression ‘]' }? 
fill-size ::= bit | nibble | byte | word | long 
Alignment 
alignment ::= align 4lign-size 
align-size ::= nibble | byte | word | long 
Switch-type 
switch-type ::= switch ‘{'switch-body ‘}’ 
switch-body ::= {case case-name: case-body }+ 
case-name ::= identifier 
case-body ::= { type-statement ; }* key-constant-statement ;{ type-statement 
key-constant-statement := key data-type-specifier = declaration-constant 
Array-type 
array-type ::= {wide }? array { array-specifier }? type-body 
array-specifier ::= array-name 
‘(’expression'}’ 
array-name ::= identifier 
type-body ::= ‘{’ { type-statement ,;}* ‘}’ 


Resource—specify resource data 
resource resource-type ‘(’ resource-specifier‘)’ data-body , 
data-body ::= ‘{’ { data-statement { , data-statement }* }? ‘}’ 


data-statement ::= expression 
point-constant 
rect-constant 
String 
identifier 
switch-data 
array-data 


switch-data ::= case-name data-body 
array-data ::= ‘{’ { array-element { , array-element }* }? ‘}’ 


array-element ::= { data-statement { , data-statement }* }? 
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Preprocessor directives 
These preprocessor directives are available: 


#define identifier { define-string }? 
#undef identifier 

#if£ preprocessor-expr 

#elif preprocessor-expr 

#else 

#endif 

#ifdef identifier 

#ifndef identifier 

#printé ( string {, [ expression | string]}*) 


Preprocessor-expr is the same as expression with the following additional expressions: 


defined ‘(identifier)’ 
defined identifier 


Syntax 


This section defines the nonterminal symbols used in the previous sections. 


identifiers 


An identifier may consist of letters (A-Z, a—z), digits (0-9), or the underscore 
character ( _ ). Identifiers may not start with a digit; otherwise any mix of letters, 
digits, and underscores is acceptable. Identifiers are not case sensitive. An identifier 
may be of any length. 


Token delimiters 
token-delimiter ::= { space | tab | newline | comment }+ 


comment ::= ‘/*' { printing-character }* ‘*/’ 


Compound types 


point-constant ::= ‘(expression , expression ‘}’ 

rect-constant ::= ‘{’expression , expression , expression , expression ‘}’ 
Expressions 

bit-expression ::= expression 

byte-expression ::= expression 

word-expression ::= expression 

long-expression ::= expression 


Syntax 


expression ::= 


system-function 


Numbers 


integer-constant :: 


decimal-constant ::= 


ve 
oe 


octal-constant ::= 


hexadecimal-constant ::= 


binary-constant 


decimal-marker :: 


hex-marker ::= 
binary-marker :: 


octal-digit ::= 
hex-digit ::= 


binary-digit ::= 


literal-constant :: 


integer-constant 
literal-constant 
numeric-variable 
system-function 

expression 

— expression 

~ expression 

! expression 

‘C expression ‘)’ 

expression >> expression 
expression << expression 
expression expression 
expression ‘||’ expression 
expression && expression 
expression ‘|’ expression 
expression & expression 
expression ‘= expression 
expression == expression 
expression >= expression 
expression <= expression 
expression > expression 
expression < expression 
expression - expression 
expression + expression 
expression * expression 
expression / expression 
expression % expression 


$Scountof ‘(’ array-name'‘)’ 


decimal-constant 


octal-constant 
binary-constant 
hexadecimal-constant 


nonzero-digit { digit }* 
0 { octal-digit }* 
hex-marker { hex-digit }+ 


binary-marker { binary-digit }+ 


0a | OD 
Ox | Ox! $ 
Ob | OB 


OLAS ars b6a7 


Ol1I121314I15161718191 


AIBICIDIEIEF! 


albilcldlel€f 


Ol1 


' { character }* ' 
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Variables 


string-variable ::= $$Version 
$$Date 
$$Time 
$$Name 
$$Shel1' (’" Shell-variable-name"')’ 
$$Resource'('file, resource-id, resourceName-or-ID‘)’ 
$$Format ( string{ ,[ expression | string]}*) 


resourceName-or-ID  ::= resource-id 
resource-name 


numeric-variable ::= $$Hour 
$$Minute 
$$Second 
$$Year 
$$Month 
$$Day 
$SWeekday 
$$Type 
$$ID 
$SAttributes 


Strings 


String ::= simple-string 
hex-string 
string-variable 
String String 


simple-string ::= " { character }* " 

hex-string ::= $" { hex-digit hex-digit }* " 

character ::= printing-character | escape-character 
escape-character ::= \ escape-code 

escape-code ::= character-escape-code | numeric-escape-code 
character-escape-code ::= nitlibiri£ivi2i\ltin 


numeric-escape-code ::= { octal-digit }3 
decimal-marker { decimal-digit }3 
hex-marker { hex-digit }2 
binary-marker { binary-digit }8 


syntax 


Appendix E 


File Types, Creators, 
and Suffixes 


File types and creators 
Table E-1 lists MPW file types and creators. 


Table E-] 

File types and creators 

File Type Creator 

MPW Shell 'APPL' 'MPS '' (MPSspace) 
Tools 'MPST' 'MPS ' 

Text files 'TEXT' 'MPS ' 

Object files ‘OBJ ' 'MPS ' 

Pascal load/dump 'DMPP! 'MPS ' 


Assembler load/dump 'DMPA' 'MPS ! 


File suffixes 


File suffix conventions are as follows. 


Text files 

name.a Assembly-language source file 

name.a.lst | Assembler listing file 

name.c C source file 

name.h C header file 

nmame.map Linker map 

name.p Pascal source file 

name.r Resource description file (Resource Compiler input) 


Text files are identified by their file type (TEXT) rather than by a special suffix. 
Several applications Gncluding MacWrite, MDS Edit, and the MPW Shell) can create 
and edit files of type TEXT. The creator 'MPS ' indicates to the Finder that the MPW 
Shell is the application to launch when a text file is opened. 


EI 


Object files 


name.a.o Object file created by the Assembler 

name.p.o Object file created by the Pascal Compiler 

name.c.o Object file created by the C Compiler 

name.o ‘Object file Cibrary) created by Lib; object files shipped with MPW 


Compilers add the suffix *.o” to the source file name to construct the object file 
name. The language suffix is left in the name in order to prevent name conflicts for 
programs whose components are written in several languages. (For example, a 
program might have source files MacGismo.a and MacGismo.c and object files 
MacGismo.a.o and MacGismo.c.o.) 
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Appendix F 


Object File Format 


This appendix is addressed to programmers who are writing compilers or assemblers 
to run under MPW. 


Object file format 


An object file consists of a sequence of object file records. These records are in the 
data fork of the file. There are 11 types of object file records: 


QQ The first record in the file must be a first record. 

One-byte pad records are used to maintain word alignment 
Comment records allow comments to be included in the file. 
Dictionary records associate names with unique IDs. 

Module records define code and data modules. 

Entry-point records define entry points in code and data modules. 
Size records specify the size of a module. 

Contents records specify the contents of a module. 


00000 0 0 0 


Reference records and computed-reference records specify locations in modules 
that contain references to other modules or entry points. 


O The last record in the file must be a Jast record. 


A module is a contiguous region of memory that contains code or static data. (The 
jump-table is considered to be code.) A module is the smallest unit of memory that is 
included or removed by the Linker. An entry point is a location (offset) within a 
module. (The module itself is treated as an entry point with offset zero.) A segment 
is a named collection of modules. 


All modules, entries, and segments are given a unique, positive, 16-bit ID. An ID is a 
file-relative number for a module, an entry point, or a segment, identifying the 
module, entry point, or segment within a single object file. 


Modules and entry points may be local or external. A local (module, entry point, or 
segment) can be referenced only from within the file where it is defined. An 
external (module, entry point, or segment) can be referenced from different files. 
In addition to an ID, each external module or entry point defined or referenced in an 
object file must also have a unique name (a string identifier) that identifies it across 
files. A module, entry point, or segment without a name is said to be anonymous. 


F-] 


Names and IDs are specified in dictionary records. Local IDs may be anonymous. (If 
no dictionary entry is found for it, an ID is considered anonymous.) Local modules 
and entries need not have unique names, and an external segment may have the 
same name as an external module or entry point. 


At any given point in an object file, there can be one current code module and one 
current data module. The beginning of a new code or data module is indicated by a 
module record. The current code and data modules are further defined by 

entry point, size, contents, reference, and computed-reference records—these 
records can occur in any order after the module record. In each of these records, a 
flag bit indicates whether the record refers to the code or the data module. 


The structure and semantics of each of the record types is defined below. 


Notation used in this appendix 
Each record type is represented by a diagram such as the following: 


} 10 | toos| recor eo | or |e 
differ- short/ code/ 
7 6 5 4 3 2 ] 0 


Figure F-1 
Record type prototype 


offsets 


The first box illustrates the record. Each block represents a byte. The first byte 
indicates the record type, in this case, 10. The /lags byte is expanded in the second 
box. The record size is a signed, 16-bit integer that indicates the total length of the 
record (including the record type byte, flags byte, and record size field). Hence, any 
one object file record is limited to 32K bytes. (This is not a limit on the size of the 
module, because partial contents can be placed in several records.) 


The second box represents the flag bits. In this example, they are interpreted as 
follows: 


Bit Meaning 


0 0 indicates code, and 1 indicates data 

1,2 Must always be 0 

3 0 indicates short and 1 indicates long 

4-5 0 indicates 32 bits, 1 indicates 16 bits, and 2 indicates 8 bits 
6 Always 0 

of 1 indicates a difference computation 


** Note: All unspecified bits must be zero. 
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Object file records 
This section defines each of the object file record types. 


Pad record 


is) 


Figure F-2 
Pad record 


A pad record is a single byte that is always zero. A pad record follows any record 
whose length is an odd number of bytes, in order to maintain word alignment. 
(Other than pad records, all records are word-aligned.) 


First record 


0 


Figure F-3 
First record 


The first record in an object file must be a first record. 


If the nested bit in the flags field is one, then the Linker interprets all references to 
undefined ID-name pairs as external references. If the nested bit is zero, the Linker 
will try to match the name of an undefined symbol with a local name before treating 
the undefined symbol as external. 


The version field contains a version number that is 1 for the current definition of the 
object file format. 


Last record 


pate 


Figure F-4 
Last record 


The last record in an object file must be a last record. 
Object file records 
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Comment record 


Figure F-5 
Comment record 


comments | 


A comment record allows comments to be included in an object file. It has no effect 
on the semantics of the object file. 


The record size field specifies the total number of bytes in the record. 


“i 


A dictionary record associates a name with an ID (or several names with several IDs). 
At most one dictionary record may appear for a given ID in a single object file. 


Dictionary record 


Figure F-6 
Dictionary record 


strings 


The record size field specifies the total number of bytes in the record. 


The strings field contains one or more names, each of which is preceded by a length 
byte. 


The first name in the strings field is associated with the ID given in the first ID field. 
The second name is associated with first D+1, and so on. 


The dictionary record for an ID must appear before the module or entry-point 
record that defines the ID, but need not appear before reference or computed- 
reference records that refer to the ID. If an ID has no dictionary record or has a name 
with a length of zero, it’s considered anonymous. 


Module record 


.. |local/ code/ 
Main | ext, data 
4 3 2 ] 0 


Figure F-7 
Module record 


“* Note: Bit 7 now means “Force Active.” 


F-4 Appendix F: Object File Format 


A module record associates an ID with a module, and makes that module the current 
code or data module. All entry-point, size, contents, reference and computed- 
reference records help define the current code or data module. 


Modules may contain either code or data: 


O For code modules, the segment ID field specifies the segment in which the code is 
placed. Segments may be named or anonymous. Named segments are treated as 
external; anonymous segments are local. (If the segment is named, the dictionary 
record specifying the name must appear before the segment ID can be used in a 
module record.) 


O For data modules, a nonzero size field specifies the size of the module. In this case 
size or contents records are unnecessary. (The size of a module can also be 
specified by a size record, or implicitly by the offset of the last byte in a contents 
record.) | 


Modules may be either Jocal or external. (Local modules may be anonymous.) 


A code module flagged as main becomes the execution starting point of the 
program. A data module flagged as main becomes the main program data area, just 
below the location pointed to by A5. At most one main code module or entry point 
and one main data module may appear in an object file. | 


If a code or data module has the force active bit set, then the Linker will not strip that 
module, even though it is not referenced by any other module and even though it is 
not the main module. 


References to a module are considered to be references to the first byte of the 
module. ; 


Entry-point record 


local/ code/ 
Main | ext. data 
4 3 2 ] 0 


Figure F-8 
Entry-point record 


An entry-point record declares an entry-point ID. The entry point is in the current 
code or data module, as indicated by bit 0 of the flags field. 


The offset field gives the byte offset of the entry point relative to the beginning of the 
module. The offset of an entry point may be outside the module (for example, a 
virtual base for an array). . 


Flags: An entry point may be defined for either a code or a data module. Entry 
points may be either local or external. (Local entry points may be anonymous.) A 
code entry point flagged as main becomes the execution starting point of the 


program. At most one main code module or entry point may appear in an object 
file. _* 


a Object file records 
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Size record 


J 7 | roar] tio sno 
code/| . 
data 
0 


Figure F-9 
size record 


A size record specifies the size of the current code or data module. The size is in 
bytes. The bytes within a module of size N are numbered 0, 1, ..., M-1. The size of a 
module may also be specified in a contents record, or (for data modules) in the 
module record. If more than one size is specified, the largest size given is taken as the 
size of the module. 


“* Note: In allocating records, the Linker rounds the size of a module up to a 
multiple of two, to ensure that modules are word-aligned in memory. 


Contents record 


j 8 | too] rood exo 
empl./ code/ 
4 3. 2 1. 0 


Figure F-10 
Contents record 


(offset) (repeat) contents 


Contents records specify the contents of the current code or data module. 
The record size field specifies the total number of bytes in the record. 


Either complete or partial contents may be specified. If partial contents are 
specified, the first four bytes of the contents field specify the byte offset of the 
contents from the beginning of the module. 


The contents may be either the bytes to be placed in the module, or a 2-byte repeat 
count followed by the bytes to be repeated. (If both an offset and a repeat count are 
specified, the offset comes first.) 


Multiple contents records per module are permitted, in any order. The offset of the 

last byte for which contents are specified determines the module’s total size. (Size ed 
specifications may also appear in the module record, and in size records—if more: 

than one size is specified, the largest size given is taken as the size of the module.) 
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Reference record 


a 


7 


Figure F-11 
Reference record 


A reference record specifies a list of references to an ID. The references are from the 
current code or data module, and may be to either code or data. 


The record size field specifies the total number of bytes in the record. 
The ID field specifies the module or entry point being referenced. 


The offsets field specifies a list of byte offsets from the beginning of the current code 
or data module. These offsets may be either short (16 bits) or Jong (32 bits). The 
location modified may be either 32 or 16 bits. Multiple references to the same or 
overlapping locations are permitted. References from code may indicate instruction 
editing (that is, whether an offset is A5- or PC-relative). . 


References fall into four categories: from code to code, from code to data, from data 
to code, and from data to data. 


m Code-to-code references: If the A5-relative flag is 1, the A5-relative offset of a 
jump-table entry associated with the specified module or entry is added to the 
specified location. No instruction editing is performed. 


If the A5-relative flag is 0, the Linker selects either PC-relative or A5-relative 
addressing. The immediately preceding 16-bit word is assumed to contain a JSR, 
JMP, LEA, or PEA instruction, and is modified to indicate either PC-relative or 
A5-relative addressing. If the referenced module or entry point and the current | 
code module are in the same segment, the PC-relative offset of the module or 
entry point is added to the contents of the specified location. If they are in 
different segments, the A5-relative offset of a jump-table entry associated with the 
specified module or entry is added to the specified location. 


In either case, the location may be 32 or 16 bits. (32-bit PC-relative and 
A5-relative address modes are available for the MC68020, but not for the 
MC68000.) 


Note: To indicate a PC-relative code-to-code reference, a somipile: or assembler 
should use a computed-reference record. 


m= Code-to-data references: The A5-relative flag must be 1 for code-to-data 
references. The A5-relative offset of the specified data module or entry is added to 
the contents of the specified location. No instruction editing is performed. The 
location may be either 32 or 16 bits. (32-bit A5-relative addressing is available for 
the MC68020, but not for the MC68000.) 


Object file records 
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m= Data-to-code references: If the A5-relative flag is 1, the AS5-relative offset of a 
jump-table entry is added to the specified location, which may be either 32 or 16 
bits. 

If the A5-relative flag is 0, the memory address of a jump-table entry associated - 
with the specified module or entry is added to the contents of the specified 

_ location, which must be 32 bits. (Note that this requires a runtime operation that 
‘adds the actual value of A5 to the A5-relative offset.) 


m Data-to-data references: If the A5-relative flag is 1, the A5-relative offset of the 
module or entry is added to the specified location, which may be either 32 or 16 
bits. ; 


If the A5-relative flag is 0, the memory address of the specified module or entry is 
added to the contents of the specified location, which must be 32 bits. (Note that 
this requires a runtime operation that adds the actual value of A5 to the 
AS5-relative offset.) 


Computed-reference record 


differ- short/ code/ 
7 6 5 4 3 2 ] 0 


Figure F-12 
Computed-reference record 


offsets . 


A computed-reference record specifies a list of computed references based on two 
specified IDs. | 


The record size field specifies the total number of bytes in the record. The references 
are from the current code or data module, and may be to either code or data. 


The ID1 and ID2 fields specify the modules or entry points being referenced. If ID1 
specifies a code reference, ID2 must also be a code reference in the same _ 
segment—if ID1 is a data reference, ID2 must also be a data reference. 


The only computation provided is difference. 


The offsets field specifies a list of byte offsets from the beginning of the current code 
or data module. These offsets may be either short (16 bits) or long (32 bits). The 
location modified may be either 32, 16, or 8 bits. A 0 in bits 4 and 5 indicates 32; 1 
indicates 16; and 2 indicates 8. 


The value of the address of ID1 minus the address of ID2 is added to the contents of 
the specified location. Multiple references to the same or overlapping locations are 
permitted. 
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Appendix G 


In Case of Emergency 


This appendix contains some information that may be useful when serious system 
errors occur. 


Crashes | 


If you end up in the debugger (MacsBug) while running MPW, it may be possible to 
recover without rebooting and losing your recent changes. The debugger displays the 
register contents followed by a “>” prompt Type G SYSRECOVER. The Shell will 
attempt to recover by aborting the current command, saving the contents of all the 
windows, and/or returning to the Finder. If this fails, type ES to return to the Finder, 
then shut down the system immediately. 


Stack space 


The MPW Shell and tools that run integrated with the Shell share a single stack. The 
stack size is determined by the Shell at initialization time. Complex command files, 
large links, and other tools may require more stack space than is available. System 

_ errors 28, 2, and 3 are possible indications of this problem. You can increase the 
stack size by using ResEdit to modify 'HEXA' resource number 128 in the file MPW 
Shell. The default size is $2710 (10,000 bytes) when less than 480,000 bytes are 
available for the application heap and $4E20 (20,000 bytes) when more than 480K 
are available. 
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active window: The frontmost window. The 
Shell variable {Active} always contains the name 
of the current active window. 


alias: An alternate name for a command, 
defined with the Alias command. 


application: A program that mins stand-alone, 
outside of the Shell environment. An 
application's file type is APPL. 


blank: A space or a tab character (in the context 


of separating words in the command language). 


build commands: Shell commands that are 
output by the Make tool, used to build a program. 


build command line: In the dependency rule of 
a makefile, the lines beginning with a space or tab 
that follow the dependency line. 


built-in commands: Editing commands, 
structured commands, and other Shell 
commands that are part of the MPW Shell 
application (as opposed to MPW tools, which are 
separate files on the disk.) 


- code resource: A resource that contains a 
program’s code—most commonly a resource of 
type 'CODE' (for applications and MPW tools), 
but other resource types such as 'DRVR' and 
'PDEF' also contain code. 


command file: See script. 


command name: The first word ofa _ 
command, identifying the name of a built-in 
command or the name of a file (tool, command 
‘file, or application) to execute. 


command script: See script. 


command substitution: The replacement of a 
command by its output. Command substitution 
takes place within back quotes C...>). 


console: The window where a command is 
entered and executed (standard input). Also, the 
window to which the command's output is 
returned (standard output). 


current selection: The currently selected text 
in a window. In editing commands, the current 
selection in the target window is represented by 
the § metacharacter. 


data fork: The part of a file that contains data 
accessed via the Macintosh File Manager. 


data initialization interpreter: The module 
_DATAINIT in the libraries RunTime.o and 
CRuntime.o. 


- dependency file: A makefile. 


dependency line: In Make, the first line of a 
dependency rule. 


dependency rule: In Make, a rule that specifies 


the prerequisite files of a given target file, along 
with a list of the commands needed to build the 
target file. 


dependent: In a Commando dialog, a control 
that is enabled or disabled depending on the state 
of its parent control. 


desk accessory: A “mini-application,” 
implemented as a device driver, that can be nun at 
the same time as an application. Desk accessories 
are files of type DFIL and creator DMOV, and are 
installed by using the Font/DA Mover. 


device driver: A program that controls the 
exchange of information between an application 
and a device. 


diagnostic output: Commands and tools send 
error and progress output to diagnostic output 

(by default, the window where the command was 
executed). You can redirect diagnostic output to 
another file, window, or selection with the 2 and 
22 operators. 


dialog: In Commando, the programmed 
interaction between a user and a tool or script. A 
dialog may utilize more than one dialog box. 


dialog box: A window that appears when a 
command is invoked, offering options and 
parameters. 


Editor: When appearing with initial capitals, the 
built-in commands appearing in MPW’s Edit 
menu, a part of the MPW Shell: 


entry point: A location (offset) within a 
module. 


escape character: The Shell escape character is 
d (Option-D). It is used to disable (or “escape”) 
the special meaning of the character following it, 
to continue commands over more than one line 
(Return), and to insert invisible characters into 
command text. 


external: A module, entry point, or segment 
that can be referenced from different object files. 


external reference: A reference to a routine or 
variable defined in a separate compilation or 
assembly. 


filename: A sequence of up to 31 printing 
characters (excluding colons), that identifies a 
file. See also pathname. - 


file type: A four-character sequence, specified ~ 
when a file is created, that identifies the type of 
file. (Examples: TEXT, APPL, MPST.) 


Finder information: Information that the 
Finder provides to an application upon starting it, 
telling it which documents to open or print. 


Font/DA Mover: An application, available on 
the System Tools disk, used for installing desk 
accessories in the System file. 


full pathname: A pathname that contains 
_ embedded colons but no leading colon. 


HFS: “Hierarchical File System,” used on 800K 
disks and the Apple Hard Disks. 


ID: A file-relative number for a module, .an entry 
point, or a segment, identifying the module, 
entry point, or segment within a single object file. 


insertion point: An empty selection range; that ™ 


is, the character position where text will be 
inserted (marked with a blinking vertical bar). 


‘Integrated Environment: A set of routines, 
modeled on the C language, that provide 
parameter passing, access to variables, and other 
functions to MPW tools. (See Chapter 13.) 


interface routine: A routine called from Pascal 
whose purpose is to trap to a certain ROM or 
library routine. 
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jump table: A table that contains one entry for 

every routine in an application or MPW tool, and 
is the means by which the loading and unloading 
of segments is implemented. 


leafname: A partial pathname that contains no 
colons. © 


literal: In the Resource Compiler, a value within 
single quotation marks. (See Chapter 8.) 


local: A module, entry point, or segment that can 
be referenced only from within the file where it is 
defined. 


location map: The Linker can write to standard 
output a map of memory segments sorted by 
segNum and segOffset. See Chapter 10.) 


main segment: The segment containing the 
main program. 


makefile: A file used by the Make command, 
which describes dependencies between the 
various pieces of a program, and contains a set of 
commands for building up-to-date files. The 
default makefile is named MakeFile. 


module: A contiguous region of memory that 
contains code or static data. A module is the 


~ smallest unit of memory that is included or 


removed by the Linker. 


MPW Shell: The application that provides the 
environment within which the other parts of the 
Macintosh Programmer’s Workshop operate. The 
Shell combines an editor, command interpreter, 
and built-in commands. 


MPW tool: An executable program (type MPST) 
that is integrated with the MPW Shell environment 
(contrasted with an application, which runs 
stand-alone). Like applications, tools exist as 
separate programs on the disk. 


‘non-HFS: The nonhierarchical file system, used 


on 400K disks and Macintosh XL hard disks. 


option: A command-line switch, specifying 
some variation from a command's default 
behavior. Options always begin with a hyphen (-). 


parameter: The words following the keyword in 


a simple command. There are two types of 


parameters: options and files. Note that certain 
parameters, such as I/O redirection, are 
interpreted by the Shell and never seen by the 
command itself. 


parent: In Commando, an option or control 
whose status determines whether a dependent 
option or control is enabled or disabled. 


partial pathname: A pathname that either 
contains no colons or has a leading colon. 


pathname: A sequence of up to 255 characters 
that identifies a file or directory. A full pathname 
is a pathname that contains embedded colons but 
no leading colon. A partial pathname either 
contains no colons or has a leading colon. A 
leafname is a oles pathname that contains no 
colons. 


pattern: A literal text pattern (such as 
/ABCDEFG/), or a regular expression. Patterns 
are a case of selection, and always appear between 
the pattern delimiters /.../ or \...\. 


pipe: The command terminator | is the pipe (or 
pipeline) symbol. It causes the output of the - 
preceding command to be used as the input for 
the subsequent command. (See Chapter 5, 

Table 5-1.) 


position: In editing commands, position refers 
to the location of the insertion point. 


prefix: The directory portion of a filename. 


prerequisite file: In Make, the files that must | 
exist or be up-to-date before the target file can be 
built. 


pseudo-filename: Any device name that you 
can use in place of a filename, but that has no disk 
file associated with it. Any command can open a. 
pseudo-filename. These are most often used for 
I/O redirection. 


quotes: A set of characters that literalize the 
enclosed characters, used for aivabing special 
characters. The quote symbols are '...', "...", 
\...\, and /.../. The escape character, d, quotes 
the character that follows it. 


reference: The location within one module that 
contains the address of another module or entry. 


regular expressions: A language for specifying 
text patterns, using a special set of 
metacharacters. (See Appendix B, Table B-2.) 


regular expression operators: A special set of 
metacharacters used in regular expressions and 
filename generation. (See “Pattern Matching” in 
Chapter 6.) 


resource: Data or code stored in a resource file 
_ and managed by the Macintosh Resource 
Manager. 


resource attribute: One of several 
characteristics, specified by bits in a resource 
reference, that determine how the resource 
should be dealt with. 


resource compiler: A program that creates 
resources from a textual description. The MPW 
Resource Compiler is named Rez. 


resource description file: A text file that can _ 
be read by the Resource Compiler and compiled 
into a resource file. The Resource Decompiler 
disassembles a resource file, producing a 
resource description file as output. 


resource file: Common usage for the resource 
fork of a Macintosh file. 


resource fork: The part of a file that contains 
data used by an application, such as menus, 
fonts, and icons. An executable file’s code is also 
stored in the resource fork. 


root: In a makefile, a top-level target that is not a 
prerequisite of any other target. 


script: An ordinary text file (type TEXT) 
containing a series of commands. The entire file 
can be executed by entering the filename. A script 
is also referred to as a command file or 


' command script. 


segment: One of several parts into which the 
code of an application may be divided. Not all 
segments need to be in memory at the same time. 


selection: A series of characters, or a character 
position, at which the next editing operation will 
occur. Selected characters are inversely 
highlighted in the active window, and outlined in 
other windows. A selection is used as an argument 
to most editing commands, and can be specified 
by using a special set of selection operators. (See 
Appendix B, Table B-1.) 


signal: An event that diverts program control 
from its normal sequence. (See Chapter 13.) 


signature: Each Macintosh application has its 


" own unique signature (or creator). For example, 


creating a file with the type DFIL and signature 
DMOV tells the Font/DA Mover that this file 
contains desk accessories. See the Finder 
Interface chapter of Inside Macintosh. 


simple command: Any command consisting 
of a single keyword followed by zero or more 
parameters. 


standard error: Diagnostic output. 
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standard ipl: Input that is typed cay. into 
a window (the console). 


standard output: Output that is returned to tie 
window where its command or program was 
typed. 


Startup file: A special command file containing 
commands that are executed each time the Shell 
is launched. Startup executes a second command 
file called UserStartup. 


’ status panel: The panel in the lower left corner 
of the Worksheet window. The status panel shows 
what command MPW is executing. Clicking in the 
Status panel is equivalent to pressing the Enter 
key. 


status value: A code returned by commands in 
the Shell variable {Status}. Zero indicates 
successful completion of the previous command, 
and other values usually indicate an error. 


structured command: Any command that. 
controls the order in which other commands are 
executed. For and If are examples of structured 
commands. All structured commands are built 
into MPW and usually have more than one 
keyword. See also simple command. 


target selection: The current selection in the 
target window, represented by the § character. 
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target file: In Make, a file that is to be rebuilt 
and that depends on one or more prerequisite 
files. 


target window: The second window from the 
front—this is the default target for editing 
commands that are entered in the active window. ° 
The Shell variable {Target} always contains the 
name of the current target window. 


tool: See MPW Tool 


type declaration: In the Resource Compiler, a 
statement that specifies the pattern for any 
associated resource data by indicating data types, 
alignment, size, and placement of strings. 


user interface: The system or set of | 
conventions by which the user interacts with 
software. In addition to the standard Macintosh 
mouse-and-menu interface, MPW includes both a 
command language and a dialog user interface 
(Commando). 


word: A single, blank-separated element in a 
command. A command name and each of its 
parameters are separate words in the command 
language. 


Worksheet window: The main work area in 


MPW; the window usually used as the console. 
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. left brace ({) 8-15 . 
less-than symbol (<) 11-7, 11-8 
{Libraries} 5-12 
library construction 10-19-21 
{Libs} 10-13 
Lib tool 
-df option 10-14, 10-20 
library construction 10-19-21 
Line 6-2 
line continuation character 10-8 
line number, selection by 6-6 
Link 4-19, 5-2, 9-2 
-Ssg option 10-14, 10-15 
-sn option 10-14, 10-15 
Linker 1-7, 9-5-6, 10-13, F-3 
controlling code resources 10-17 
functions, 10-14—15 
-If option 10-18 
location map 10-18 
-l option 10-18 
-ma option 10-17. 
optimizing 10-19 
RAM caches 10-19 
-ra option 10-16 
resolving symbol definitions 
10-17 » 
-rt option 9-9 
segmentation 10-15-16 
setting resource attributes 10-16 
-Sg option 9-9 
“sn option 9-9 
-uf option 10-20 
-w option 9-6 
linking 9-5-6, 10-14-19 
desk accessory 9-9 
driver 9-9 
MPW tool 9-13 
{LinkOpts} 10-13 
Listings 10-13, 10-14 
Literal 3-9 
literals 8-21 
local module 10-17, F-1 
locked 8-8 
logical operators 5-24 
longint 8-10, 8-11- 
Loop 5-21 
Loop...End 5-20 


M 

MacDraw 1-9 

MacInterfaces 10-13 

Macintosh application, structure 9-4 

Macintosh Programmer’s Workshop. 
See MPW 

MacPaint 5-2, 5-6, 7-10 
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MacsBug 1-9 
A-trap commands 11-14-16 
boot code 11-3 
break commands 11-12-13 
command language 11-7-8 
command summary 11-20-21 
disassembler commands 
11-18-20 
exceptions 11-4-5 
general commands -11-9 
heap zone commands. 11-16-17 
installing 11-2-3 — 
memory commands 11-10-11 
memory usage 11-4 
using 11-5—6 
MacWrite 3-2 
Magic Return 11-13 
makefile 2-4-5 
comments 10-9 
debugging 10-10-11 
format 10-2-3 
modifying 9-12 
quoting 10-8 
variables 10-7-8 
MakeLoad 10-13 
{MakeObjs} 10-13, 10-14 
MakeOut 10-9 


‘Make-p-o 10-13 


Make tool 1-7, 10-2-14 

-d option 10-7 

-r option 10-9 

-s option 10-10 

-u option 10-10 

-V option 10-10 
{MakeUses} 10-13 
MakeX 10-13 
Mark 3-2, 6-2, 6-8 
Mark... 3-12_ 
markers 3-12~13, 6-8-9 
Markers 6-2 
Mark menu 2-4, 3-2, 3-12-13 
MDSCvt 2-2 
MDSCvt.Directives 2-2 
MemMgr 10-13 
memory commands, MacsBug 

11-10-11 
memory management, MPW 
Shell 13-9-10 

Memory Manager 11-3, 12-10 
menu bar 2-4 
menu commands, defining 5-32 
menuName 4-23 
menus. See specific menu 
metacharacters 6-9, 6-13, 6-14 
minus sign (-) 6-11, 11-8 
$$Minute 8-23 
module record F-2, F-4-5 


modules 10-14, F-1 
external 10-17, F-1 
local 10-17, F-1 

$$Month 8-23 

Mount 4-7 

Move 4-7 

MPW 
building a program 2-4—10 
commands 2-4 
command scripts 1-5 
distribution files A-1-3 
editing functions 4-2 
entering commands 4-2-6 
files and directories 1-10 
installation 2-2 
operators C-1-3 
RAM caches 2-3 
Starting 2-3 


- {MPW} 4-12, 5-11 


MPW Assembler 1-6, 2-2 
files A-3~-4 
-print option 4-16 
MPW C 
files A-5~7 
using MacsBug 11-6 
MPW Pascal 1-6 
files A-4—5 
MPW Shell 1-2-4 
built-in commands 1-2, 1-4 
conventions 13-11 
editing commands 1-3 
editing features 3-2 . 
exit processing 13-7 
file format 3-2 
file management commands 1-3, 
4-7~8 
icon 2-3 
initialization 13-8 
memory management 13-9-10 
menu commands 3-3-16 
parameters 13-2-3 
running applications outside 5-6 
signal handling 13-6 
standard I/O channels 13-46 
status codes 13-7 
structured commands 1-4, 
5-19-24 
variables 4-12, 5-9-14, 13-4 
window commands 1-2 
MPW tools 1-5-8 
building 9-13 
linking 9-13 
MPWTypes.r 8-3, 9-10 
MultiDirs 14-26 
MultiFiles 14-26, 14-27, 14-28, 
14-30 
MultiInputFiles 14-26 
MultiInputFilesAndDirs 14-26 
MultiOutputFiles 14-26 


N 

$S$Name 8-23 

negation symbol (7) 6-11 

New 4-7, 7-3, 7-5, 7-6 

New... 3-4 

Newer 4-7 

{NewerDeps} 10-14 

NewFolder 4-7, 4-20 

No Input 4-19 

nonpreload 8-8 

nonpurgeable 8-8 — 

No Output 4-19 

Notepad desk accessory 4-15 

numbers 5-24, 8-21, D-6 
MacsBug 11-7 

_ number sign (#) 4-5, 5-6, 10-9, 

11-7 
numeric types 8-11 


O 
object files 
format F-1-2 
records F-3-8 
suffixes E-2 
onexit 13-7 
Open 3-2, 4-2, 4-7, 7-3, 7-5, 7-6 
Open... 3-4 
Open a... 7-6 
Open General 7-5, 7-6 
Open Selection 3-4, 4-2 
Option-5 5-31 
Option-6 5-31, 6-5 
Option-8 6-13 
Option-D 5-5 
Option-F 10-2, 10-3 
Option-J 6-7 
Option key 4-13 
Option-key characters B-3 
Option-L 6-11 
options 5-4 
Option-semicolon 4-13, 4-14, 14-2 
Option-X 3-10, 4-13, 6-11 
output 
diagnostic 5-29 
redirecting 5-26-30 
standard 4-3, 5-26, 5-28 
Output File... 4-19 
output files, single 4-19 


Pp 
pad record F-1, F-3 
Page Setup... 3-5 
_ parameters 
command 5-4, 5-22 
MPW Shell 13-2-3 
Parameters 5-22, 5-25 
parent 14-16 


parentheses [()] 5-5, 5-26 
Pascal 
strings 8-24 
using MacsBug 11-6 
Pascal Compiler 5-12 
PasMat 2-2, 4-20 
PasRef 2-2 
Paste 3-6, 6-2, 7-5, 7-7 
pathnames 4-9-11 
full 4-9 
variables 4-12 
pattern 6-9 
matching 6-9-14 
Perf.c 12-2 
PerfControl 12-3, 12-6 
PerfDump 12-2, 12-3, 12-6 
performance measurement tools 
«1-8 
using 12-5-6 
performance output file 12-6-8 
performance reports 12-6-10 
interpreting 12-10 
performance tools 
bucket counts 12-4 
components 12-2-3 
implementation issues 12-10-11 
using. 12-3 
PerformLib.o 12-2 
PerformReport 12-2, 12-3, 12-6 
analyzing results 12-9 
-€ option 12-9 
interpreting 12-10 
Perf.p 12-2 
PictOrlcon 14-16 
(PInterfaces} 5-12 
pipe symbol (1) -5-5 
{PLibraries} 5-12 
plus sign (+) 6-12, 11-8 
point 8-10 
point types 8-12 
pop-up menus 4-16-17, 14-11-13 
output file 4-19 
position 6-7 
preload 8-8 
preprocessor directives 8-4, 
8-19-20, D-5 
prerequisite files 10-2 
#printf 8-20, D-5 
{PrintOptions} 5-12 
Print Selection 3-5, 5-12 
print tool, header options 4-22 
Print Window 3-5, 5-12 
program 
building 9-2-4 
segmenting 10-15-16 
Program Counter 11-11, 12-2 
sampling 12-3-4 
protected 8-8 


pseudo-filenames 5-30 
pstring 8-10, 8-12 
purgeable 8-8 


Q 

question mark (?) 4-13, 11-9 

QuickDraw 13-8 

Quit 1-9, 3-5, 5-8, 7-4, 7-5 

quotation marks (' and ") 5-17, 8-6. 
See also back quotes 

quoting, makefile 10-8 

quoting special characters 4-8, 5-2, 
5-15-17 


R 
radio buttons 2-10, 3-9, 4-15, 
14-7-8 
dependencies 14-20 
Random 13-8 
read 8-4, 8-8, D-2 
Reboot 11-9 
rect 8-10 
rectangle types 8-12 
reference 10-17 
reference record F-1, F-6-7 
regular expressions 1-3, 3-2, 6-9, 
B-2-3 
operators 3-10, 5-25, 6-10 
repeated instances 6-12 
tagging 6-12-13 
Rename 4-7 
Replace 3-11, 6-2, 6-12 
Replace... 3-8 
Replace Same 3-8 
ResEdit 1-9, 5-2, 9-2 
customizing 7-12-14 
extensibility 7-2 
file window 7-5 
uses 7-2 
using 7-3-11 
ResEqual 8-4 
resource, editing 7-7-11 
resource 8-4, 8-5, 8-13, 8-16-18, 
D-2, D-4 
S$Sresource 8-23, 9-9, 9-10 
resource attributes 8-8 
setting 10-16 
Resource Compiler. See Rez 
Resource Decompiler. See DeRez 
resource description expression 
Operators 8-22 
resource description file 8-2 
Commando 14-3-4 
structure 8-4-5, D-2-4 
syntax notation D-1 
resource description statements 
8-6-18 


Index IN-5 


resource description syntax 
_ 8-21-25 
resource fork 9-4 
Resource Manager 11-3 
resource template, creating 
7-12-14 
resource type 7-6-7 
window 7-6 _ 
Restore 10-13 
Resume 1-9, 5-8 
Revert 4-7, 6-2, 7-5, 7-6 
Revert to Saved 3-5 
Rez 1-8, 4-19, 5-12, 7-2, 9-2 
DeRez and 8-2 
escape sequences 8-25 
first dialog box 4-20 
input file 9-10 
nested Preprocessor dialog 
box 4-21 .- 
nested Redirection dialog box 
4-21 
using 8-3-4 
variables 8-23 
Rez command line, -undef 
option 8-19 
RezDet 1-8 
right brace character (}) 5-9, 8-15 
{RIncludes} 5-12 
roots 10-2, 10-13 
Runtime.o 9-6 


Ss 

sample text panel 7-10 

Save 3-4, 4-7 

Save a Copy... 3-5 

Save as... 3-4 

scripts 1-5, 1-9, 5-2, 5-7 
parameters 5-13 

scrolling 4-15 

Search 6-9 

Search Backward 3-9 

searching, forward and backward 

6-14 

$$Second 8-23 

_ segmentation 
Linker 10-15-16 
performance tools 12-11 

segments 10-14, F-1 

Select All 3-6 

selection 6-3-9, B-1-2 
extending 6-7 
by line number 6-6 
marker 6-8-9 
operators 6-4 
position 6-7 

Selection Expression 3-9, 3-10 


IN-6 Index 


semicolon (;) 4-13, 5-20, 8-6, 8-15 
Send to Back 7-9 
Set 4-12 
Set Byte 11-10 
SetDirectory 3-13, 4-8, 9-11 
Set Directory 2-6, 2-9 
Set Directory... 3-14 
SetFile 4-7, 14-15 

-a option 4-23 
Set Memory 11-10 
SetPrivileges 4-8, 14-15 
SetVersion 4-8 
SFGetFile 4-19 
SFPutFile 4-19, 4-20 


$$Shell 8-23 


{ShellDirectory} 5-10 

Shift 5-21, 5-22 

Shift Left 3-7 

Shift Right 3-7 

Show Build Commands 3-16 
Show Clipboard 3-6 

Show Directory 2-5, 2-6, 3-14 
Show Full Build Commands 3-16 
Show Invisibles 3-2, 3-7 

signal 13-6 

signal handling, MPW Shell 13-6 
Signature 9-7 

sigpause 13-6 

sigrelease 13-6 


_. simple commands 5-6 


simple command terminator G) 5-5 

single quotes (‘) 11-7 

size record F-1, F-6 | - 

slashes 3-10 

{SourceFiles} 10-13 

square brackets ({]) 6-11, 8-12 

stack, MPW Shell 13-10 

Stack Crawl 11-17 

stack space G-1 

Stack Windows 3-11 

standard input 4-3, 5-26, 5-27-28 

standard output 4-3, 5-26, 5-28 

Startup 1-9, 2-3, 4-4, 5-2, 5-8 
variables 5-11-12 

static 10-20 

{Status} 5-10 

status codes, MPW Shell 13-7 

Status Panel 2-3, 5-3 

Status Register 11-11 

status value 5-3-4 

StdErr 5-30 

StdIn 5-30 

StdOut 5-30 

Step 11-12 

Step Spy 11-13 

Step Till 11-13 

string 8-10, 8-12 


Strings 8-24-25, D-7 
MacsBug and 11-7 
operators 5-24 
types 8-12 

structured commands 1-4, 5-6, 

5-19-24 

Suspend 1-9, 5-8 

switch 8-10, 8-14 

switch types 8-14 _ 

Symbol Dump 11-18 

Symbol Exchange 11-18 

symbols, MacsBug 11-8 

SymMgr 10-13 


sysheap 8-8 


System Folder 11-2 
{SystemFolder} 5-10 
SysTypes.r 1-8, 8-3 


T 
Tab 3-7, 6-2 
{Tab} 5-12 


tagging operator (®) 5-24 


- Target 4-8, 5-9, 6-2 


{Target} 5-10 

TargetFile 10-4 

target file 10-2 

target window 4-2, 4-9 

terminal D-1 | 

TermPerf 12-3 ve 

{Test} 5-11 

text files, suffixes E-1 

Text Only 3-2 

text string 8-24 

TextTitle 14-10 

three-state buttons 14-15 

Tile Windows 3-11 

$$STime 8-23 

Time Manager 12-3 

TLACvt 2-2 

TLACvt.Directives 2-2 

token delimiters D-5 

{ToolDir} 10-13 

tools 5-2 

Tools folder 2-2 

Total Display 11-11 

Total Floating Point 11-11 

Trace 11-12 

Transfer 7-4 

Translate 6-2. 

Try Cursor 7-8 

type 8-4, 8-5, 8-9-13, 8-15, D-2, 
D-3-4 

$$Type 8-23 

type declaration 8-4 


Types.r 1-8, 8-3, 8-5, 8-15 


U 
unchanged 8-8 
#fundef 8-19, D-5 
Undo 3-6, 6-2, 7-7 
unlocked 8-8 
Unmark 3-2, 6-2 
Unmark... 3-13 
unprotected 8-8 
unsigned 8-11 
Use Full Window 7-9 
user interface 1-2 
Use RSRC Rect 7-9 
UserStartup 1-9, 2-4, 3-14, 4-4, 
5-8, 9-11 
Utilities 10-13 


Vv 
variables D-7 
defining and modifying 5-13-14 
exporting 5-14 
makefile 10-7-8 
MPW Shell 5-9-14, 13-4 
pathname 4-12 
predefined 5-10 
Rez 8-23 . 
$$Version 8-23 
Volumes 4-8 


W 
$$Weekday 8-23 
Where 11-20 
Which 4-8 
wildcard characters 3-10, 4-13, 5-2, 
5-25, 6-11 
Window menu 2-4, 3-11 
windows 
commands 1-2 
MPW Shell 13-10 
names 4-8~—13 
typing commands in 4-3 
Windows 4-8 
{Windows} 5-10 
window template 7-12 
{WordSet} 5-12 
{Worksheet} 5-10 
Worksheet window 2-3, 2-7, 3-11, 
5-28 — 
Wrap-Around Search 3-9 
wstring 8-10, 8-12 


Y . 
$$Year 8-23 
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Part Il 


Command Reference 


Syntax 


Description 


Type 


Input 


Output 


Part II is a command dictionary that describes each of the Macintosh Programmer’s 
Workshop 2.0 commands. When you have become sufficiently familiar with the 
material in Part I, you can rémove Part II to a smaller separate binder for convenient 
desktop reference. Please be sure to read the next section, “Command Prototype,” 
which explains the format for all command descriptions and defines the basic 
behavior of all commands. 


Command prototype 


The following command prototype illustrates the conventions that we’ve used to 
describe MPW commands. Most commands behave roughly as specified below. 


Command. [ option... ] [ file... ] 


Note: Filenames, command names, and options are not sensitive to case. The syntax 
notation itself is described in the preface in Part I. 


The first word of the command is the filename of the program to execute, or the name 
of a built-in command. The subsequent words are passed as additional parameters to 


. the command (or recognized by the Shell in the case of I/O redirection). 


Most commands recognize two distinct types of parameters: options and filenames. 
Options begin with a hyphen (-) to distinguish them from filenames. Although the 
syntax descriptions list the options first, options and files may appear in any order. 
All of the options apply to the processing of all of the files, regardless of the ordering 
of options and files. 


For commands that read and write text files, you may ier a file, a window, or a 
selection within a window, as follows: 


name Named window or file 

§ The selection in the target window (the second window from the 
top) 

name.§ The selection in the named window 


Commands may fall into one of three categories: Tool, Script, or Built-In. This 


_ information is useful when you need to figure out why a command isn’t working. For 


example, if you know that the command is a tool or a script, you can deduce that 
maybe the file is missing or that there is a file of the same name in the current 
directory. 


Standard input is often processed if no filenames are specified. 


Note: lf a program is reading from standard input, you can press Command-Enter (or 
Command-Shift-Return) to indicate EOF and terminate input. (See sbemmunauny a 
Command” in Chapter 4.) 


Text processors usually write their output to standard output. The Assembler writes 
listings to standard output. The Linker writes location maps to standard output. 


II-2 . Command prototype 


Diagnostics 


Status 


Options 


Limitations 


See also 


Errors and warnings are written to diagnostic output. If no errors or warnings are 
detected, most commands don’t write anything to diagnostic output. Assembler and 
Compiler error messages have the format 


### message 

File "filename" ; Line linenumber 

This format makes it possible to select and execute the text after “###”, because the 
names “File” and “Line” have been defined as Shell commands—‘File” is defined in 
the Startup file as an alias for the Target command, and “Line” is a short command 
file that finds a line number. 


Several commands write progress and summary information to diagnostic output if 
you specify the -p option. 


Status values are returned in the {Status} variable. A value of 0 indicates that no errors 
occurred; anything else usually indicates an error. Typical values are 


0 . Command succeeded 
1 Incorrect options or parameters 
2 Command failed; invalid input 


Positive numbers are returned by tools, scripts, and built-in commands. Negative 
numbers are returned by the Shell only. 


Options specify some variation from the default command behavior. Options begin 
with a hyphen (-) to distinguish them from files and other parameters. 


Options form single words in the command language. Some options require 


- additional parameters, which are separated from the option name with a blank. (An 
_ option’s parameters also form a single word in the command language.) If more than 


one option parameter is required, the usual separators between them are commas 
and equal signs. For example, 


Asm -define gaecesstans -pagesize 84,110 


Note that spaces are not allowed between option parameters and their separating 
commas. For those options that do have additional parameters, the option 
parameters are never optional. 


Options may appear in any order. All options are collected prior to processing files. 


A few commands may have special cases or warnings that you should know about. Be 
sure to check for a Limitations heading at the end of the command’s reference. 


“Structure of a Command” in Chapter 5. 


Command prototype H-3 


Syntax 


Description 


Type 


AddMenu—add menu item 
AddMenu [ menuName [ itemName [ command... }]] 


Associates a list of commands with the menu item ftemName, in the menu 


- menuName. If the menu menuName already exists, the new item is appended to the 


bottom of that menu. If the menu menuName doesn’t already exist, a new menu is 
appended to the menu bar and the new item is appended to that menu. When the new 
menu item is selected, its associated command list is executed just as though the 
command text had been selected and executed in the active window. 


Note: The command text that you specify for an AddMenu item is processed _ 
twice—once when you execute the AddMenu command itself, and again whenever 
you subsequently select the new menu item. This means that you must be careful to 
quote items so that they are processed at the proper time. See the “Examples” section 


. below. 


You can also use AddMenu to display information for existing user-defined menus, 
by omitting parameters: 


O If command is not specified, the command list associated with itemName is 
written to standard output. 


Q If itemName and command are both omitted, a list of all user-defined items for 
menuName is written to standard output. 


OG If no parameters are specified, a list of all user-defined items is written to standard 
output. 


(This output is in the form of AddMenu commands.) 


You can define keyboard equivalents, character styles, and other features for your 
new menu commands—itemName can contain any of the metacharacters that are 
used with the AppendMenuC( ) procedure documented in the Menu Manager 
chapter of Inside Macintosh: 


/char _ Assign the keyboard equivalent Command-char. 


tchar __ Place charto the left of the menu item. 

An - Item has an icon, where 7 is the icon number. See Inside Macintosh. 
( Item is disabled (dimmed). 

<style Item has a special character style: style can be any of the following: 

B Bold | 

I Italic 

U Underline 

O Outline 

S Shadow 


Be sure to quote menu items containing these special characters. (See the “Examples” 
section below.) | 


Note: Semicolons (;) cannot be used within an itemName. 
Menu items can’t be appended to the Window, Mark, or Apple menus. 


Built-in. 


Il-4 - AddMenu 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 


None. 


If any of the optional parameters is omitted, a list of user-defined menu items and 
their associated commands is written to standard output. 


Errors and warnings are written to diagnostic output. 


AddMenu may return the following status values: 


0 No errors 

1 Syntax error 

2 An item can’t be redefined 
3 System error 


None. 


AddMenu 


Lists all user-defined menu items. 


AddMenu Extras "TimeStamp/P" 'Echo “Date’' 


Adds an “Extras” menu with a “TimeStamp” item, which writes the current time and 
date to the active window. This item has the Command-key equivalent Command-P. 


AddMenu File 'Format<B' 'Erase 1! 


Adds a “Format” item to the File menu (as discussed under the Erase command), and 
makes the item bold. 


AddMenu Find Top 'Find « "{Active}"! 


Adds the menu item “Top” to the Find menu, and defines it as the Find command 
enclosed in single quotes—this command places the insertion point at the beginning 
of the active window. 


Note: The following attempt to do the same thing will not work: 
AddMenu Find Top "Find « (Active}" 


This command won’t work because the {Active} variable will be expanded when the 
menu is added. (It should be expanded when the menu item is executed.) In the first 
(correct) example, the single quotes defeat variable expansion when the AddMenu 
command is executed, they are then stripped off before the item is actually added. 
The double quotes remain, in case the pathname of the active window happens to 
contain any’ special characters. 


You may want to add some or all of the following commands to your UserStartup file: 


AddMenu Find '(-'! val 
AddMenu Find 'Top/6' © 'Pind * "({Active}"™! 
AddMenu Find 'Bottom/5'! 'Find o "(Active}"™'! 


These commands create several new items in the Find menu. The first is a disabled 
separator that creates a new section at the bottom of the menu. The Top and Bottom 
items position the insertion point at the top and bottom of the active window. Both 
menu items have Command-key equivalents. 


AddMenu _—sECsiI-5 


See aiso ' DeleteMenu command. 


“Quoting Special Characters,” “How Commands Are Interpreted,” and “Defining 
Your Own Menu Commands” in Chapter 5. 


“Creating a Menu in Your Program” in the Menu Manager chapter of Inside 
. Macintosh. 


-6 ©  AddMenu 


Syntax 


Description 


Type 

Input 
Output 
Diagnostics 


Status 


Options 


Examples 


See also 


Adjust— adjust lines 
Adjust [-c count] [ -l spaces] selection [ window] 


Finds and selects the given selection, and shifts all lines within the selection to the 
right by one tab, without changing the indentation. 


If a count is specified, count instances of selection are affected. The -1 option lets you 


move lines by any number of spaces to the left or right. 
If you specify the window parameter, the command operates on window. It’s an 


error to specify a window that doesn’t exist. If no window is specified, the command 


Operates on the target window (the second window from the front). 


Built-in. 
None. 
None. 


Errors are written to diagnostic output. 


Adjust may return the following status values: 


0 At least one instance of the selection was found 
1 Syntax error 
Z Another error 


_ -¢ count - Repeat the select-and-adjust operation count times. 


-l spaces Every line within the selection will be shifted spaces to the right. 
You can shift a selection left by specifying a negative value for 
spaces. 


Adjust -1 4 § 


Shifts the lines containing the target selection to the right by four spaces. 


Adjust -1 -8 /if/A:A/else/ 


Selects everything after the next “if’ and before the following “else”, and shifts all 
lines within the selection to the left by eight spaces. 


Align command. 


““Selections” in Chapter 6. 


Adjust 


Il-7 


Syntax 


Description 


Type. 

| Input 

Output 
Diagnostics 


Status 


Options 


Example 


See also 


II-8 Alert 


Alert—display an alert box 
Alert [-s] [ message... ] 


Displays an alert box containing the prompt message. The alert is displayed until its 
OK button is clicked. If the message contains any special characters, you'll need to 
quote it, as explained in Chapter 5. 


Built-in. 


_ Reads standard input for the message if no parameters are specified. 


None. 
None. 


Alert may return the following status values: 


0 No errors 
1 Syntax error 


-S Run silently. Do not beep when the dialog box is displayed. 


Alert Please insert next disk to be searched. 


Displays the following alert box, and waits for the user to click “OK” before euiiag 


Please insert nent disk to be searched. 


Confirm and Request commands. 


Syntax 


Description 


Type 
Input 


Output 


Diagnostics 


Status 


Options 


Examples 


See also 


Alias—define or write command aliases 
Alias [ name [ word...]] 


Name becomes an alias for the list of words. Subsequently, when name is used as a 
command name, word... will be substituted in its place. 


If only name is specified, any alias definition associated with name is written to 
standard output. If name and word are both omitted, a list of all aliases and their 
values is written to standard output. (This output is in the form of Alias commands.) 


Aliases are local to the script in which they are defined. An initial list of aliases is 
inherited from the enclosing script. Inherited aliases may be overridden locally. You 
can make an alias definition available to all scripts by placing the definition in the 
UserStartup file. 


You can remove aliases with the Unalias command. 
Built-in. 
None. 


When parameters are omitted, the Alias command writes aliases and their values to 
standard output. 


Errors are written to diagnostic output. 


Alias may return the following status values: 


0 No errors 
1 The specified alias could not be found 


None. 


Alias Dir Directory 


Creates an alias “Dir” for the Directory command. 


Alias Top 'Find °«' 

Creates an alias “Top” for the command “Find ¢” (which places the insertion point at 
the beginning of a window). The command takes an optional window parameter, and 
by default acts on the target window. The Top command could now be used as follows: 
Top # find top of target window 


Top Sample.a # find top of window Sample.a 
# (equivalent to "Find « Sample.a") 


’Unalias command. 


“Command Aliases” in Chapter 5. 
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Syntax 


Description 


Type 

Input 
Output 
Diagnostics 


Status 


Option 


Examples 


See also 
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Align—align text to leff margin 
Align [-c count] selection [ window] 


All lines within each instance of the selection are positioned to the same distance 
from the left margin as the first line in the selection. 


If you specify the window parameter, the Align command will act on window. It’s an 
error to specify a window that doesn’t exist. If no window is specified, the command 
operates on the target window (the second window from the front). 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


Align may return the following status values: 


0 At least one instance of the selection was found 
1 Syntax error 
2 Any other error 


-c count Repeat the select-and-align operation count times. 


Align § 


Same as the Align menu item; that is, aligns all lines in the default selection with the 
first line of the selection. | | 


Align /Begin/:/End/ 


Selects everything from the next “Begin” through the following “End”, and aligns all 
lines within the selection to the same margin position as the line that contains the 
“Begin”. 


Adjust command. 


“Selections” in Chapter 6. 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status — 


Asm—MC68xxx Macro Assembler 
Asm [ option... 1[ file... ] 


Assembles the specified assembly-language source files. One or more filenames may 
be specified. If no filenames are specified, standard input is assembled and the file 
“a.o” is created. By convention, assembly-language source file names end in the 
suffix *.a”. Each file is assembled separately—assembling file name.a creates object 
file name.a.o. The object file name can be changed with the -o option. 


See the MPW 2.0 Assembler Reference for details of the assembly language. The first 


Commando dialog box for this command is reproduced here for convenience. 


Tool. 


If no filenames are specified, standard input is assembled. (You can terminate input 
by pressing Command-Enter.) 


If either the -l or the -s option is specified, an assembler listing is generated. If 
standard input is used for the source file, the listing is written to standard output. If the 
input is taken from file name.a, the listing is written to name.a.lst. The listing file 
name can be changed with the -lo option. 


Errors and warnings are written to diagnostic output. If the -p option is specified, 
progress and summary information is also written to diagnostic output 


Asm may return the following status values: 


0 No errors detected in any of the files assembled 
1 Parameter or option errors 

2 Errors detected 

3 Execution terminated 


Asm l-71 


Options Except for the -case on option, options may appear in any order. 


-addrsize size =Set address displays in the listing to size digits (values 4 to 8 are 
allowed). The default is 5 digits. 


Options 

Warnings ——_——_-—_—__—___-_—_, 
{@ Show ail warnings 
© Suppress ail warnings | 


Defines: [© Suppress only branch warnings! 
-Case————, Progress — 
|@ off lo off 
}O on | |Q Fult 

iO object | i© Time only; 


eel 


Listing Options... 


Command Line 
—=. ~ | 
MCS8i0cx Macre Assembler : 
| [so Asm 


-blksize blocks Set the Assembler’s text file I/O buffer size to blocks 512 bytes. 
Values 6 to 62 are allowed. Odd values are made even by reducing 
the value by 1. The default value is 16 (8192 bytes) if the Assembler 
determines it has the memory space for the I/O buffers, and 6 (3072 
bytes) otherwise. This option permits optimization of I/O 
performance (transfer rate for text file input, load/dump files, and 
listing output) as a function of the disk device being used. Note that 
increasing the blocks value reduces the amount of memory 
available for other Assembler structures (such as symbol tables). 


-case on Distinguish between uppercase and lowercase letters in non-macro 
names (same as CASE ON). (Case is always ignored in macro 
names.) If you intend to preserve the case of names declared by the 
-define option, then the -case on option must precede the -define 
option(s) in the command line. 


-case objlect] Preserve the case of module, EXPORT, IMPORT, and ENTRY 
names. only in the generated object file. In all other respects, case 
is ignored within the assembly, and the behavior is the same as the 
preset CASE OFF situation. 


-case off Ignore the case of letters. All identifiers are case insensitive. This is 
the preset mode of the Assembler, but it may be used in the 


command line to reverse the effect of one of the other -case modes. 


-c{heck] Syntax check only. No object file is generated. 
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-d{efine] namel=valuel {,name[=value] )... 


Define the name as having the specified value. The value is a 
decimal integer. If value is omitted, a value of 1 is assumed. This . 
option is equivalent to placing the directive 


name EQU value 


at the beginning of your source file. Note that in order to test 
whether or not the name is defined, you should use the &Type 
function. You can define more than one name by specifying 
multiple -d options or multiple name[=value] parameters 
separated by commas. For example, 


Asm -d debugl1, &édebug='on' 


-d{efine] &namel[=[valuel] [,&namel=[valuel] ]... 


Define the macro name as having the specified value. The value is a 
decimal integer or a string constant. If the “=value’ is omitted, the 
decimal value 1 is assumed. If only the value is omitted, the null 
string is assumed. -define is equivalent to declaring the name as a 
global arithmetic symbol (GBLA for an integer value) or global 
character macro symbol (GBLC for a string value) and placing one 
of the following directives at the beginning of the source file: 


&mame SETA value 
&mame SETC value 


Note that in order to test whether the name is defined, you should 
use the &Type function. You can define more than one macro 
name by specifying multiple -d options or multiple &name [=value] 
parameters separated by commas. 


-elrrlog] filename 


-f 


Write all errors and warnings to the error log file with the specified 
filename (same as ERRLOG ‘filename'). 


Suppress page ejects (same as PRINT NOPAGE). 


-font [fontnamel] {, fontsize] 


-h 


Set the listing font to fontname (for example, Courier), and the size 
to fontsize. This option is meaningful only if the -s or the -1 option is 
used; both may not be omitted The default listing font is Monaco 7. 
Note that listings will be formatted correctly only if a monospaced 
font is used. 


Suppress page headers (same as PRINT NOHDR). 
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Asm 


-i pathname (,pathname)... 


l 


-lo listingname 


-O objname 


Search for include and load files in the specified directories. 
Multiple -i options may be specified. At most 15 directories will be 
searched. The search order is as follows: 


1. The include or load filename is used as specified. If a full 
pathname is given, then no other searching is applied. 


If the file wasn’t found, and the pathname used to specify the file 
was a partial pathname (no colons in the name or a leading 
colon), then the following directories are searched. ° 


2. The directory containing the current input file. 
3. The directories specified in -i options, in the order listed. 
4. The directories specified in the Shell variable {AIncludes}. 


Generate full listing. If file mame.a is assembled, the listing is 


written to 2ame.a.|st. 


Pathname for the listing file and directory for the listing scratch file. 
If listingname ends with a colon (:), it indicates a directory for the 
listing file, whose name is then formed by the normal mules (that is, 
inputFilename.a.|st). If listingname does not end with a colon, the 
listing file is written to the file listingname. In this case, listings for 
multiple source files are appended to the listing file. In either case, 
the directory implied by the listing name is used for the Assembler’s 
listing scratch file. The -lo option is meaningful only if the -s or 

the -1 option is used. 


Pathname for the generated object file. If objname ends with a 
colon (:), it indicates a directory for the output file, whose name is 
then formed by the normal rules (that is, inputFilename.o). If 
objname does not end with a colon, the object file is written to the 
file objname. (in this case, only one source file should be specified 
to the Assembler.) 


-pagesize [/] [,w] Set the listing page size. (This option is meaningful only if the -s or 


-l option is specified; both may not be omitted.) The Jand w 
parameters are integers: / is the page length (default = 75) and wis 
the page width (default = 126). (These settings assume that 
Monaco 7 is being used with the MPW Print command to the 
LaserWriter.) 


-print mode [,mode]... 
Set a print option mode. Mode may be any one of the following 
PRINT directive options: 


[NO]GEN Macro expansions 
[NO]PAGE Page ejects 
[NO]WARN Warnings 
[NOJMCALL Macro calls 
(NO]OBJ Object code 
{NO]DATA Data 

{NOIMDIR Macro directives 


[NOJHDR Page headings 
{NO]JLITS Literals 

{NO]STAT Progress information 
[NO]SYM Symbol table display 


See the MPW 2.0 Assembler Reference for a discussion of these 
PRINT settings. You can specify more then one print option by 
specifying multiple -print options or multiple mode parameters 
separated by commas. For example, 


Asm -print nowarn,noobj, nopage 


Note that single-letter options are provided for some of the settings: 
-f (NOPAGE), -h (NOHDR), -p (STAT), and -w (NOWARN). 


-p Write assembly progress information (module names, includes, 
loads, and dumps) and summary information (number of errors, 
warnings, and compilation time) to the diagnostic output file. CThis 
option is the same as PRINT STAT.) 


-S Set PRINT NOOBJ to generate a shortened form of the listing file. If 
the -I option is also specified, the rightmost option takes 
precedence. 

-t Display the assembly time and the number of lines to the diagnostic 


file even if progress information Cp) is not being displayed. 


-w Suppress warning messages (same as PRINT NOWARN). 
-wb Suppress branch warning messages only. 
Example Asm -w -l Sample.a Memory.a -d Debug 


Assembles Sample.a and Memory.a, producing object files Sample.a.o and 
Memory.a.o. Suppresses warnings and defines the name “Debug” as having the 
value 1. Two listing files are generated: Sample.a.lst and Memory.a.lst. (Sample.a 
and Memory.a are located in the AExamples directory.) 


See also MPW Assembler 2.0 Reference. 
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Syntax 


Description 


Type 


Input 


Backup—folder file backup 
backup [ option ... ] -from folder -to folder| file ... ] 


Files in a source (“from”) folder are copied to a destination (“to”) folder based on the 
modification date. By default, only files that already exist in both the source and 
destination folders are candidates for copying. (The -a option can override this 
default.) Backup does not actually do the copies. Instead, a script of MPW Shell 
duplicate commands is generated. 

Backup’s default operation is built on the premise that you already have an existing 
folder on two sets of disks (generally a hard disk and a set of 3.5-inch disks—drive 
numbers may be specified as folder “names”) and that you want to make sure that the 
files on one of the disks are the same as the files on the other disk. Thus it is the files on 
the destination (“to”) disk that determine which files can be copied from the source 
(“from”) disk. 


A Shell duplicate command is generated to the standard output file if 

O a file on a source disk also exists on the destination disk, and 

O the file has the same file type and creator, and 

O the modification date of the source is newer than that of the destination. 


In addition to the basic function of generating Shell duplicate commands, Backup 
also provides these services: 


O Folders can be recursively processed, allowing processing of folders contained 
within folders (-r). 


O Compare commands can be generated for out-of-date files of type TEXT to 
discover why the files are different (compare). 


G Filenames that exist on one disk and not on the other can be displayed 
(-check from,to). 


O File folder names that don’t exist on the destination can be displayed 
(-check folders). 


O Filenames in the destination that are mewer that the source can be displayed 
check newer). 


Tool. 


None. 
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Output 


Diagnostics 


Status 


For each file to be copied, a Shell duplicate command is generated to the standard 
output file as follows: 


Duplicate -y FromFile ToFile 


The duplicate’s -y option may be suppressed by using Backup’s -y option. If you are 
using the -e option, then the Shell’s Eject commands will be generated at the end of 
the list of duplicates. These commands eject the source and/or destination disks if 
either or both disks are specified as disk drive numbers 1 or 2 as the -from and -to 
option parameters. 


If you use the -compare option, a Compare command will be written to the standard 
output file if the files are of type TEXT. Note that only the Compare will be generated if 
you specify-compare only. You can also specify additional Compare command 
options with the Backup -compare option. 


Errors and warnings are written to the diagnostic output file. If you specify the 

-p option, and the diagnostic file is not the same as the standard output file, then a 
summary of all duplicate commands generated will be written to the diagnostic output 
file. The summary will show the modification dates of both the source and destination 
files. If you use the -check option, then a report of any files in one folder that don’t 
exist on the other folder, and any files in the destination folder that are newer than the 
source, is written to the diagnostic output file. You can redirect this report to a file by 
using the -co option. 


Backup may return the following status values: 


0 No errors; Shell duplicate commands have been generated or filenames were 
listed 

1 Parameter or option errors 

2 Execution terminated 

3 Noerrors and no files to duplicate or list 


Note: Backup will return status value 3 when no files need copying. If there is no 
copying because none of the files in the source folder exists in the destination folder, 
Backup will also report a warning to the diagnostic output file. If there are no name 
matches, it is possible that your from/to pathnames were specified incorrectly. 
Hence, Backup lets you know of the possible error. Backup will not report this as an 
error if you use the -l, -a, or -since option. 
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Spiions -a Normally, if a file in the destination (“to”) does not exist in the 
source (“from”), then it is ignored. Using the -a option forces 
Backup to generate a Shell duplicate command for all files in the 
source that don’t exist in the destination. 


-alt If you use this option with the -m (“multi-disk”) option, Backup will 
alternate the drive numbers when it asks for additional disks. This 
option has meaning only if either -from or -to, but not both, 
specifies a disk drive (1 or 2). 


Backup Options 
Source/Destination Folders Search Criteria 


Select “From” Directory... C) Recursive Type [| 


oy ere RENE 
setect te irectorue J |[sincepete[ 


Drive Options Check Report Options 
CJ Files not in “to” Output Files 
2 Sane (J Files not in “from" MULE 


(0 “to"s newer than “from"s 
OC) Alternate dives FJ ralders notin "t0- More Options... 


Command Line 
[eee | 


Files in a source (“from”) folder are copied to a destination ("to") folder 


based on the modification date. Backup does no actually do the copies. 
Instead a script of MPY Shell duplicate commands is generated. 


-c Create folders. When a folder name doesn’t exist in the destination 
disk, and there are files in the source to copy, -c generates a Shell 
newfolder command to create the folder on the destination disk. 
Note that this option makes sense only if you are using the -a option. 


-check checkopt,checkopill... 
Produce reparts on the source and destination based on the 


checkopt parameters. Checkopt may be any one of the following 
parameter words: 


from Report all files in the source (“from”) folder that don’t 
exist in the destination (“to”). 


to Report all files in the destination (“to”) folder that 
don’t exist in the source (“from”). 


allfroms Same as from, but report ail folders processed, even 
if there are no files in that folder to report. 


alltos Same as to, but report all folders processed, even if 
there are no files in that folder to report. 


folders Report all source (“from”) folders that don’t exist as 
destination (“to”) folders when recursively (-r) 
processing folders. Note: only the outermost folder 
names are reported. 


newer Report all files in the destination (“to”) that are newer 
that the source (“from”). 


Note that the -check option is ignored if the -since option is used. 
I-18 Backup 


-co filename Normally, the -check report is written to the diagnostic output file. 
The -co option allows you to redirect the report to the specified 
filename. 


-compare only [ ,'option...'] | 
Option ...' 

Generate Compare commands for all files of type TEXT that are to 
be duplicated. If only is specified then only the compares will be 
generated and not the duplicates. Additional Compare command 
options and output redirection may by specified. Make sure that the 
compare options you include are correct, because Backup does not 
check for you. A period (.) may be used to indicate that there are no 
Compare options. Note that, in general, the Compare options have 
to be enclosed in quotes to ensure that they are not used as Backup 
options. 


-d Generate Delete commands for all files in the destination (“to”) 
folder that don’t exist in the source (“from”). If this option is 
specified then the options -check to, -check alltos, -m, and 
-Since cannot be used. 


-do only,'command...' | 
'commana...' 

Generate the command string specified by command... for all files 
that are to be duplicated. If only is specified then omly the 
command string will be generated and not the duplicates. The 
-do only option may not be specified when the -compare only 
option is specified. When the command string is generated, the 
source (“from”) and destination (“to”) pathnames are added to the 
command string as the last two (or only) parameters as follows: 


command... fromFilename toFilename 


If -sync is specified then the same command is generated but with 
one additional parameter to indicate the direction. If the source has 
a newer modification date than the destination (the standard mode 
of operation of copying the source to the destination) then the 
command string is generated, as follows: 


command... fromFilename toFilename '-->! 


If the destination has a newer modification date than the source, the 
following command string is generated: 


command... fromFilename toFilename '<--' 


If -1 is specified then -do only is implied and the command string, 
rather than a directory listing, is generated for each source 
(“from”) file, as follows: 


command... fromFilename 


-e Eject the disk from drive 1 and/or drive 2 if -from or -to specify 
drive number 1 or 2. Disks are ejected when Backup terminates if 
there are no files to duplicate. If duplicate commands are 
generated, then Shell eject commands will be generated to eject the 
specified disk(s). 
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Backup 


-from folder | drive 


-n 


-r 


-revert 


Specify the folder or drive number (1 or 2) from which to get the 
source list of files. If this option is omitted, then the list may be 
specified as a sequence of filename parameters to Backup (for 
example, “folder:=”). If both -from and a list of files are omitted, 
then drive 1 is assumed (that is, -from 1) if the -to parameter is 
explicitly specified. The -from option must be specified if -to is 
omitted or the -I option is used. You can use the Shell “wildcard” 
character, “=”, to do limited pattern matching when specifying a 
-from folder. However, you must quote such folder specifications 
in order to allow Backup (rather than the Shell) to process the 
pattern. The difference between specifying -from and supplying a 
list of filenames is that -from a/ways implies that the files belong to 
the specified folder, whereas a list of files explicitly specifies those 
files. Using -from is more efficient than using the list, but the list 
allows more complicated patterns. 


Generate a files listing of all files in the source (“from”) folder. The 
-to option cannot be specified when -1 is used. If the -do option is 
specified, then the -do command string, rather than a file listing, is 
generated for each file. 


“Multi-disk” operation. Backup will display a dialog box asking for 
additional disks to be mounted in drive 1 or 2 (depending on 
whether -from or -to specified drive 1 or 2). This option is ignored 
if both -from and -to specify disk drives. 


When recursion (-r) is specified, generate the duplicate commands 
for files nested in inner folders with leading spaces to show the 
nesting structure. 


Write Backup’s version number and a report of all duplicate 
commands generated to the diagnostic output file. The report is not 
produced if the diagnostic output file and the standard output file 
are the same. 


Recursively process subfolders encountered. 


Revert all newer files in the destination (“to”) folder to their state in 
the source (“from”) folder. The default mode for Backup is to copy 
only those files in the source folder that are newer than files of the 
same name in the destination folder. By specifying -revert, the 
copy criteria are reversed. Only files in the destination that are 
newer than those in the source are copied. This option is useful for 
reverting a newer file to its previous state in an older backup copy. 


-since datd,timel | [time] | 


filename 


Generate duplicate commands to the destination (“to”) folder for 
all files in the source (“from”) folder(s) that have a modification 
date greater than or equal to the specified date and time, or a date 
and time determined from the modification date of the specified 
filename. This is a special option that unconditionally copies files 
that satisfy the date/time requirements. Files and folders in the 
destination folder are ignored. This option is useful, for example, 
for copying to a single disk all files changed since a certain time. 
The date is specified in the form mm/dd/yy. The day (“dd”) 
and/or year (“yy”) may be omitted. The time is specified as 
hh:mm:ss. The minutes (“mm”) and/or seconds (“ss”) may be 
omitted. An entire date or the time may be omitted. If both are 
omitted, the comma is still required. If the date is omitted, the 
current date is used. If the time is omitted, time 00:00:00 is used. 


Examples 


Limitations 


As an alternative to specifying an explicit date and/or time, you 
may supply a filename. The modification date and time of that file 
will be used as the -since date and time. 


Note: Because the structure of the destination folder is ignored 
when you use the -since option, duplicate commands may be 
generated for the same filename from different source folders. It is 
recommended that you use the -y option to suppress the duplicate 
-y options when using -since. 


-sync Synchronize both source (“from”) and destination (“to”) folders. 
Files are copied in both directions; source files newer than those in 
the destination are copied to the destination, and destination files 
newer than those in the source are copied to the source. The -sync 
option may not be specified when any of the options -revert, 
-since, or -a is specified. 


Note: Use this option with caution, because it can cause copies in 
the opposite direction from that specified as -from and -to. An 
example of its safe use is with the -compare only option. This 
option will generate compare commands for all TEXT files that 
differ in their modification dates in either direction. 


-t type Consider only files of the specified type as candidates for backup. 


-to folder | drive 
Specify the folder or drive number (1 or 2) from which to get the 
destination list of files. If the -to option is omitted and the -from 
parameter is explicitly specified, then drive 1 is assumed ( that is, 
-to 1). You must specify the -to option if you omit the -from 
Option. 


-y Suppress generation of the Shell duplicate command’s -y option. 


backup ~from :HDfolder: -e 


Check that all files on the disk in drive 1 (to is omitted, so “-to 1” is implied) are up 
to date with respect to the files in :HDfolder:. If they are, the disk in drive 1 will be 
ejected. If not, the appropriate duplicate commands will be generated to update the 
out-of-date files on the disk in drive 1. An eject 1 command will be generated to eject 
the disk after the duplicate commands are processed. 


backup -r -from FServer:MPW: -to HD:MPW: -check folders 


Recursively (-r) process all the files in all the folders on FServer:MPW: to make sure 
that the files on HD:MPW: are up to date. Appropriate duplicate commands will be 
generated to copy the out-of-date files from the folders in FServer:MPW: to the 
folders in HD:MPW:. It is assumed that the folder names in HD:MPW: are the same 
as the folder names in FServer:MPW:. Any folders in FServer:MPW: that don’t exist 
in HD:MPW are skipped. Because the -check option is specified, a list of all the 
skipped folders will be written to the diagnostic file. 


“Multi-disk” (-m) operation is not supported with recursion (-r). 
The -e option is ignored when -m is specified. 


Only drive numbers 1 and 2 are supported, and are assumed to be ejectable 3.5-inch 
disk drives. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 
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Beep—generate tones 
Beep [ note [,duration [,level]]}... 


For each parameter, Beep produces the given note for the specified duration and 
sound level on the Macintosh speaker. If no parameters are given, a simple beep is 
produced. 


Note is one of the following: 


O A number indicating the count field for the square wave generator, as described in 
the Summary of the Sound Driver chapter of Inside Macintosh. 


O A string in the following format: 
[ 2] leter[# | b] 


nis an optional number between —3 and 3 indicating the octaves below or above 
middle C, followed by a letter indicating the note (A-G) and an optional sharp (#) 
or flat (b) sign. 


The optional duration is given in sixtieths of a second. The default duration is 15 
(one-quarter second). 


The optional sound /evel is given as a number from 0 to 255. The default level is 128. 
Built-in. 

None. 

None. 

None. 

A status value of 0 is always returned. 

None. 


Beep 


Produce a simple beep on the speaker. 


Beep 2C,20 '2C#,40' 2D,60 


Play the 3 notes specified: C , C sharp, and D, all two octaves above middle C, for 
one-third, two-thirds, and one full second respectively. Notice that the second 
parameter must be quoted; otherwise the sharp character (#) would indicate a 
comment. 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Begin...End—group commands 


Begin 
commana... 
End 


Groups commands for pipe specifications, conditional execution, and input/output 
specifications. Carriage returns must appear at the end of each line as shown above, 
or be replaced with semicolons (;). If the pipe symbol (|), conditional execution 
operators (&& and | |), or input/output specifications (<, >, >>, 2, 22) are used, the 
operator must appear after the End command, and applies to all of the enclosed 
commands. 


Note: Begin and End behave like left and right parentheses. Once the Begin 
command has been executed, the Shell will not execute any of the subsequent 
commands until it encounters the End command, so that input/output specifications 
can be processed. 


Built-in. 
None. 
None. 
None. 


The status value of the last command executed is returned. (fF no commands appear 
between Begin and End, 0 is returned.) 


None. 
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Examples 
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The following commands save the current variables, exports, aliases, and menus in 
file SavedState. 


Begin 


Set 

Export 

Alias 

AddMenu 
End > SavedState 


Notice that the output specification following “End” applies to all of the commands 
within the Begin...End control command. This command is identical to the 
following: 


(Set; Export; Alias; AddMenu) > SavedState 


The commands Set, Export, Alias, and AddMenu write their output in the form of 
commands; these commands can be executed to redefine variables, exports, aliases, 
and menus. Therefore, after executing the above commands, the command 


Execute SavedState 


will restore all of these definitions. You must “execute” the command file so that the 
variables and aliases are applied to the current scope. 


Note: This technique is used in the Suspend command file to save state information. 
CYou might want to take a look at Suspend, which also saves the list of open windows 
and the current directory.) The Resume file runs the file that Suspend creates, 
restoring the various definitions, reopening the windows, and resetting the current 
directory. 


Begin...End 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 
Example 


See also 


Break—break from For or Loop 
Break [ If expression | 


If expression is nonzero, Break terminates execution of the immediately enclosing 
For or Loop command. (Null strings are considered zero.) If the “If expression” is 
omitted, the break is unconditional. (For a definition of expression, see the Evaluate 
command.) 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


Break may return the following status values: 


Q No errors detected 
-—3 Break is found outside a For...End or Loop...End, or the parameters to Break are 
incorrect 
-5 Invalid expression 


None. 


Set Exit 0 
For file in Startup UserStartup Suspend Resume Quit 
EnTab "{file}" > temp 
Break If {Status} != 0 
Rename -y temp "(file)" 
Print -h "{file}" 
Echo "(file}" 
End 


This For loop entabs and prints each of the special MPW command files, the Break 
command terminates the loop if a nonzero status value is returned. (See the For 
command for further explanation of this example.) 


For, Loop, and If commands. 


Evaluate command (for a description of expressions). 
“Structured Commands” in Chapter 5. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 


BuildMenu—create the Build menu 


BuildMenu 


Creates the Build menu shown below. Each of the items in the menu is 
described in Chapter 3. 


Create Build Commands... 


Build cea %8 


Full Build... 
Show Build Commands... 
Show Full Build Commands... 


Script. 


None. 


None. 


Errors are written to diagnostic output. 


A status value of 0 is always returned. 


None. 


BuildMenu 


Creates the Build menu. This command should appear in the UserStartup file to 
create the Build menu. 


“Building a Program: An Introduction” in Chapter 2. 
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Syntax 


Description 


Type 
Input 


Output 


Diagnostics 


Status 


Option 


Example 


See also 


BuildProgram—build the specified program 
BuildProgram program [options...] 


Builds the specified program. A simple transcript of the build, including timing 
information and commands used to do the build, is written to standard output. 


Make is used to determine the commands needed to do the build. If file 
program.make exists, it is used as the makefile. If not, file MakeFile is used. 


The options specified are passed directly to Make, and control the generation of the 
build commands. BuildProgram is used to implement the Build and Full Build menu 
items in the Build menu. 


Script. 
None. 


A transcript of the build, including timing information and the commands used to do 
the build, is written to standard output. 


Errors that occur during the generation of the build commands or during the build are 
written to diagnostic output. 


Status value 0 is returned if the build is completed without error. If an error occurs 
during the generation of the build commands, the status value returned by Make is 
returned. If an error occurs during the build, the status value returned by the build 
step that detected the error (such as Asm, Link) is returned. 


The options specified are passed directly to Make, and control the generation of the 
build commands. Although other Make options may be used, the most useful is -e. 


-e Rebuild everything, regardless of dates. The specified program is 
completely rebuilt, ignoring any up-to-date object files or other 
temporary files that may already exist. 


Open "(Worksheet}" 
BuildProgram -e Count >> "{Worksheet}" 22> Dev:StdoOut 


Completely rebuilds Count. The Worksheet window is brought to the front. The 
transcript of the build, and any errors, are written at the end of the Worksheet. The 
Full Build menu item is implemented using similiar commands. 


“Building a Program: An Introduction” in Chapter 2. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 
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C—C Compiler 
C [ option...] [ file] 


Compiles the specified C source file. Compiling file Name.c creates object file 
Name.c.o. (By convention, C source file names end in a “.c” suffix.) If no filenames 
are specified, standard input is compiled and the object file “c.o” is created. 


See the MPW C 2.0 Reference for details of the C language definition. 


Tool. 


If no filenames are specified, standard input is compiled. You can terminate input by 
pressing Command-Enter. 


If you specify the -e option, preprocessor output is written to standard output, and no 
object file is produced. 


Errors and warnings are written to diagnostic output. If the -p option is specified, 
progress and summary information is also written to the diagnostic output. 


The following status values may be returned: 


0 Successful completion 
1 Errors occurred 


-C Include comments with the preprocessor output. This option has no 
effect unless the -e option is also specified. By default, comments 
are not written to the preprocessor output 


-d name Define mame to the preprocessor with the value 1. This is the same 
as writing 
#define name 1 


at the beginning of the source file. (The -d option does not override 
#define statements in the source file.) 


-d names=string Define name to the preprocessor with the value string. This is the 
same as writing 


#define name string 
at the beginning of the source file. 


-e Do not compile the program. Instead, write the output of the 
preprocessor to standard output. This option is useful for debugging 
preprocessor macros. 


-elems 881 


“8 


- ga 


Use MC68881 floating-point processor instructions instead of SANE 
routines for transcendental functions. This option generates code 
that can run only on a Macintosh II. The MC68881 floating-point 
processor uses less accurate but faster algorithms for transcendental 
functions. A program compiled with this option will nin faster, but 
the results may not be the same as those obtained with the SANE 
routines. This option has no effect unless the -mc68881 option is 
also used. 


Generate stack frame pointers in A6 (that is, LINK A6,x ... UNLK 
A6) for all functions. Insert the procedure name into the object 
code that follows the procedure’s RTS instruction. Use this option if 
you plan to debug the program with MacsBug. 


Generate stack frame pointers in A6 (that is, LINK A6,x ... UNLK 
A6) for all functions. 


-i pathname {,pathname)... 


-mc68020 


-mc68881 


Search for include files in the specified directories. Multiple 
-i options may be specified. At most 15 directories will be searched. 
The search order is as follows: 


1. The include file name is used as specified. If a full pathname is 
given, then no other searching is applied. 


If the file wasn’t found, and the pathname used to specify the file 
was a partial pathname (no colons in the name or a leading 
colon), then the following directories are searched. 


2. The directory containing the current input file. 
3. The directories specified in -i options, in the order listed. 
4. The directories specified in the Shell variable {(CIncludes}. 


Use the full instruction set of the MC68020 processor. This option 
generates object code that runs only on a Macintosh II. 


Use the MC68881 floating-point processor for all arithmetic 
Operations, conversions between different binary formats, and 
comparisons. This option generates code that can be run only ona 
Macintosh II. 


The -mc68881 option has the following effects: 


O establishes the extended data type to the 96-bit format used by 
the MC68881 floating-point processor 


O causes expression evaluation to be performed in floating-point 
registers 


O allows the Compiler to allocate extended variables to 
floating-point registers 


Even when this option is invoked, the Compiler generates SANE 
instructions instead of MC68881 instructions for transcendental 
functions. To override this feature, use both the -elems881 option 
and the -mc68881 option. 


Note: Use of the -mc68881 option does not set the -mc68020 
option. To get the best results on the Macintosh II, set both the 
-mc68020 and -mc68881 options. 
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Cc 


-0 objname 


“q 


-S name 


-u name 


-w 


-x55 


Pathname for the generated object file. If objname ends with a 
colon (:), it indicates a directory for the output file, whose name is 
then formed by the normal rules (that is, inputFilename.o). If 
objname does not end with a colon, the object file is written to the 
file objname. 


Write progress information (include file names, function names, 
and sizes) and summary information (number of errors and 
warnings, code size, global data size, compilation time, and 
compilation memory requirements) to diagnostic output. 


Optimize the code for speed, even if it’s necessary to make the 
object code larger. By default, the Compiler performs 
optimizations that make the code both smaller and quicker—the 

-q option will perform further optimizations that may make the code 
faster, but also larger. The -q option should be specified only for 
those parts of the program that are executed frequently—it’s 
counterproductive to specify -q on code that’s rarely executed. 


Allow the optimizer to assume that memory locations do not 
change except by explicit stores—that is, the optimizer is 
guaranteed (1) that no memory locations are I/O registers that can 
be changed by external hardware, and (2) that no memory 
locations are shared with other processes that can change them 
asynchronously with respect to the current process. This option 
must be used with extreme caution in device drivers, operating 
systems, and shared-memory environments, and when interrupts 
are present. 


Name the object code segment. (The default segment name is 
“Main”.) Because a segment may not exceed 32K bytes, large 
programs require multiple segments with different names. This 
option is overridden if the following statement appears in the 
source code: 


#define SEG mame 


Undefine the predefined preprocessor symbol name. This is the 
same as writing 
fundef name 


at the beginning of the source file. 


Suppress Compiler warning messages. (By default, warnings are 
written to diagnostic output.) 


Use MOVE #0,x instructions rather than CLR x instructions for 
nonstack addresses. This option may be useful when writing device 
drivers. 


Make bit fields of types int, short, and char be signed. (The default 
is for all fields to be unsigned.) 


Example 


Limitation 


Availability 


See also 


-2127 


-x149 


-284 


C -p Sample.c 


Always allocate 32 bits for enumerated data types, to maintain 
compatibility with Standard C. The default is to allocate 8, 16, or 32 
bits. 

Caution: This option is not compatible with the Macintosh 
interface libraries. 


Allow float, double, and comp variables to be allocated in floating- 
point registers. This option has no effect unless the -mc68881 
option is also specified. By default, only extended variables are 
allocated in floating-point registers. 


Enable language anachronisms. Warning messages are provided 
when anachronisms are encountered, and the constnucts are 
compiled. (See the MPW C 2.0 Reference for information.) 


Compiles Sample.c, producing the object file Sample.c.o. Writes progress 
information to diagnostic output. ample.c is found in the CExamples folder.) 


1 megabyte of RAM is recommended; on a Macintosh 512K, even small C programs 
may not compile. 


The C Compiler is available as part of a separate Apple product, Macintosh 
Programmer’s Workshop C. 


MPW C 2.0 Reference. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Canon—canonical spelling tool 
Canon [-s] [-a] [-c ] dictilonaryFile [ inputFile ... | 


Canon copies the specified files to standard output, replacing identifiers with the 

canonical spellings given in dictionaryFile. If no files are specified, standard input is 

processed. 

DictionaryFile is a text file that specifies the identifiers to be replaced and their new 

(or canonical ) spellings. Identifiers are defined as a letter followed by any number of 

letters or digits. (The underscore character ( _ ) is also considered a letter.) Each line 

in the dictionary contains either a pair of identifiers or a single identifier: 

O If two identifiers appear, the first is the identifier to replace, and the second is its 
canonical spelling. For example, the dictionary entry 


NIL NULL # change NIL to NULL 
changes each occurrence of “NIL” to “NULL” 


O A Single identifier specifies both the identifier to match and its canonical 
spelling—this feature is useful because the matching may be case insensitive or 
restricted to a fixed number of characters. (See the “Options” section below.) For 
example, the dictionary entry 


true 
changes all occurrences of “TRUE”, “True”, “tRUE”, and so on to “true”. 


You can specify a left context for the first identifier on each line of the dictionary by 
preceding it with a sequence of non-identifier characters. Replacement will then 
occur only if the left context in the input file exactly matches the left context in the 
dictionary. For example, if C structure component upperLeft should be replaced with 
topLeft, the dictionary might include the following: 


-upperLeft topLeft 
->upperLeft topLeft 


You can include comments in the dictionary file by using the # symbol—everything 
from the # to the end of the line is ignored. 


Note: The file Canon.Dict is a sample dictionary file that’s included with MPW. (See 
the “Examples” section below.) 


Tool. 
Standard input is read if no files are specified. 
The specified files are written to standard output with the identifiers replaced. 


Errors are written to diagnostic output. 
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Status The following status values may be returned: 


O All files processed successfully 
1 Error in command line 
2 Other errors 


Canon Options 


? C) Case sensitive 
Files to process... [1] Assembler indentifiers 


Number of significant characters fie 
Output Error 


Command Line 
ee ll 
Help 
Copies the specified files to standard output, replacing identifiers with the 
canonical spellings given in dictionary File. r 


Use case-sensitive matching. (Pattern matching is normally case 


Options -S 
insensitive.) 

-a Causes the characters $, %, and @ to be considered letters (for 
defining identifiers). This option is useful when processing 
assembly-language source. 

cn Take only the first n characters as significant. (Normally all 


characters in identifiers are significant.) 


Canon 
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Examples 


Limitations 


The file Canon.Dict, in the Tools folder, contains a list of all of the identifiers used in 
the Standard C library and the Inside Macintosh C interfaces. This list was made 
from the Library Index in the MPW C 2.0 Reference. The entries in Canon.Dict look 
like the following: 


abbrevDate 
ABCallType 
abortErr 
ABProtoType 
abs 

acos 
activateEvt 


owe 


The following command copies the file Source.c to the file Temp; identifiers whose 
first eight characters match a dictionary entry are replaced with that entry. 


Canon -c 8 "(MPW}"Tools:Canon.Dict Source.c > Temp 


The -c 8 option is useful when porting source from other systems where only eight 
characters are significant. 


Note: The list of Pascal identifiers used in the Inside Macintosh interface is almost 
identical to the list used in C. The dictionary Canon.Dict can also be used to port 
Pascal programs from other systems, as long as you don’t mind using the canonical 
capitalizations for the various Standard C library identifiers. 


7 
The maximum line length in the dictionary file is 256 characters. Longer lines are 
considered an error. Identifiers and words in comment sections are replaced. 
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Syntax 


Description 


Type 

Input 
Output 
Diagnostics 


Status 


Options 


Examples 


Warning 


See also 


Catenate—concatenate files 


Catenate [ file... ] 


Catenate reads the data fork of each file in sequence and writes it to standard output. If 
no input file is given, Catenate reads from standard input. None of the input files may 
be the same as the output file. 


Built-in. 

Standard input is processed if no input files are specified. 
All files are written to standard output 

Errors are written to diagnostic output. 


The following status values may be returned: 


0 All files were processed successfully 
1 One or more files were not found 
Z An error occurred in reading or writing 


None. 


Catenate Makefile.a 


Writes Makefile.a to the active window, immediately following the command. 


Catenate Filel File2 > CombinedFile 


Concatenates the first two files and places the result in the third. If CombinedFile 
doesn’t exist, it will be created; if it exists, it will be overwritten. 


Set selection "*Catenate §°" 


Captures the selection from the target window in the Shell variable {selection}. 


Catenate >> {Worksheet} 


Appends all subsequently entered text to the Worksheet window (until you indicate 
end-of-file by pressing Command-Enter). 


Beware of commands such as 
Catenate Filel File2 > Filel 


This command will cause the original data in File1 to be lost. To append one file to 
another, use the form 


Catenate File2 >> Filel 


Duplicate command. 


“Redirecting Input and Output” in Chapter 5. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Option 


Examples 


Sée also 
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Clear—clear the selection 
Clear [-c count] selection [ window] 


Finds selection and deletes its contents. The selection is not copied to the Clipboard. 
(For a definition of selection, see Chapter 6.) 


If window is specified, the Clear command acts on that window. It’s an error to 
specify a window that doesn’t exist. If no window is specified, the command operates 
on the target window (the second window from the front). 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


Clear may return the following status values: 


0 At least one instance of selection was found 
1 Syntax error 
2 Any other errors 


-c count Repeat the select-and-delete operation coumt times. 


Clear § 


Deletes the current selection. This is like the Clear command in the menu bar, except 
that the action occurs in the target window rather than the active window. 


Clear /BEGIN/:/END/ 


Selects everything from the next BEGIN through the following END, and deletes the 
selection. 


Cut and Replace commands. 
“Selections” in Chapter 6 (see Appendix B for a summary). 


Syntax 


Description 


Type 

Input | 
Output 
Diagnostics 


Status 


Options 


Examples 


Close—close specified windows 
Close [-y | -n] [-a | windous... ] 


Close the window or windows specified by windows. If no window is specified, the 
target window is closed. If changes to the window have not been saved, a dialog box 
requests confirmation of the Close. In scripts you can use the -y or -n option to avoid 
this interaction. Use the -a option instead of windows to close all of the open windows 
(other than the Worksheet). 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


Close may return the following status values: 


0 No errors 
1 Syntax error 
2 Any other error, such as “Window not found” 


-a Close all open Shell windows (except for the Worksheet, which 
cannot be closed). This option cannot be specified when any 
windows are specified. 


-n Answer “no” to any confirmation dialogs, causing all of the 
specified windows to be closed without saving any changes. 


-y Answer “yes” to any confirmation dialogs, causing all of the 
specified windows to be saved before closing them. 


Close 


Closes the target window, prompting the user with a confirmation dialog box if 
needed. 


Close -a -y 


Saves and closes all open windows. 


Close -n Test.a Test.r 


Closes the windows Test.a and Test.r without saving any of the changes. 
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Syntax 


Description 


Type 
Input 


Output 


Diagnostics 


Status 


Options 


Examples 


See also 


Commando—display dialog box for a command 


Commando [commandname | 
[Commandname] ... 


The Commando interface lets you operate any properly configured MPW tool or 
script by using specialized Macintosh dialog boxes instead of the ordinary command 
line method. The dialogs make it easy to find options and build up complex 
command lines. 


Commands with many options and parameters may employ one or more nested 
dialog boxes. See “Commando Dialogs” in Chapter 4 for more information on the 
basics of using the Commando dialogs. Chapter 14 describes the structure of the 
Commando resource and shows how to create Commando dialogs for your own tools 
and scripts. 


Tool. 
None. 


If commando is invoked by typing Commando [commandname ], then the 
command line is simply written to standard output. If commando is invoked by typing 
[Commandname] ... (the ellipsis generated by Command-semicolon), then the 
command line is intercepted by the Shell and executed. 


Errors are written to diagnostic output. 


Commando may return the following status values: 


0 The Do It button was selected 


1 ‘The Cancel button was selected 
2 ‘Error occurred while parsing the cmdo resource 
3. Y/O or program error 


None. 
Commando Rez 


Displays the frontmost Rez dialog box shown under “Rez” in Part II. 


Rez... 


Displays the frontmost Rez dialog box shown under “Rez” in Part II, exactly as in the 
previous example. 


“Invoking Commando” in Chapter 4. 


Chapter 14. 
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Syntax 


Description 


Type 


Input 


Compare—compare text files 
Compare [ option... ] file1 [ file2] 


Compares the lines of two text files and writes their differences to standard output. 
Options are provided to compare a specific column range in each file (-c), to ignore 
blanks (-b), and to ignore case (-D. 


Both files are read and compared line-for-line. As soon as a mismatch is found, the 
two mismatched lines are stored in two stacks, one for each file. Lines are then read 
alternately (starting from the next input line in fiJe2) until a match is found to put the 
files back in synchronization. If such a match is found, Compare writes the 
mismatched lines to standard output. 


Files are considered resynchronized when a certain number of lines in the two stacks 
exactly match. By default, the number of lines, called the grouping factor, is defined 
by the formula 


G = Trunc((2.0 * Log;9@) + 2.0) 
where G is the grouping factor and M is the number of lines saved in each stack so far. 
This definition requires more lines to be the same after larger mismatches. Using this 


formula, the following table shows the grouping factor, G, as a function of the number 
of mismatched lines: 


M: Number of G: Grouping 
mismatched lines factor 
1 to 3 2 
4 to 9 3 
10 to 31 4 
32 to 99 5 
100 to 315 6 
316 to 999 7 
1000 to 3161 8 
3162 to 9999 ) 


With the default dynamic grouping, the -g option sets the lower limit for G (which must 
be at least 2, because the formula is always applied). The -s option lets you fix Gas a 
Static constant. A static G may be desirable under some circumstances, but may also 
resynchronize the files at undesirable points, especially if G is too small. It’s 
recommended that you use the default (dynamic G) first; if the results aren't 
satisfactory, try a higher minimum value of dynamic G (such as 3 or 4). If that is still 
unsatisfactory, try the static G option. 


With either option, there’s a limit on the depth of the stacks; that is, to how far out of 
synch the two files can get before they’re no longer worth comparing. For a dynamic 
G, the limit on the number of mismatched lines is 1000, but you can choose a lower 
limit with the -d option. For the static G option, typical values for Gare 1 to 5, and the 
stack depth should be between about 10 and 50 (the default limit is 25). 


Tool. 


The file1 and file2 parameters specify the two files to be compared. If file2 is 
omitted, file1 is compared to standard input. 
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Output 


Diagnostics 


Mismatched lines, optionally shown with context (-e ) or suppressed entirely (-m), 
descriptive messages, and Shell editor commands to select the mismatches, are 
written to standard output. With the -h option, some of each file’s output lines are 
displayed side by side; otherwise, the first stack’s lines are displayed before the 
second stack’s. In either case, lines are shown with their line numbers. 


The following messages appear when showing mismatches: 


Nonmatching lines (Shell editor commands) 
... both stacks are displayed... 


Extra lines in lst before <line> in 2nd (Shell editor commands) 
... lines in filel’s stack are displayed... 


Extra lines in 2nd before <line> in 1st (Shell editor commands) 
... lines in file2’s stack are displayed... 


Extra lines in lst file (Shell editor commands) 
...lines in filel’s stack are displayed... 


Extra lines in 2nd file (Shell editor commands) 
... lines in file2’s stack are displayed... 


The Shell editor commands consist of File and Line (Line is provided in the MPW 
Scripts folder) commands to select the mismatched lines. In the case of extra lines in 
one file and not the other, the selection for the missing lines is generated as an insert 
point. 


The lines displayed may be suppressed with the -m option. If you use -m the messages 
are formatted slightly differently: 
### Extra lines in 2nd file 

Shell editor commands 


When mismatched lines are shown, their context may also be displayed by the using 
the -e option. Up to n equal lines (n is specified with the -e option) in both files 
preceding and succeeding the mismatches will be displayed like this: 


...preceding context lines ... 
... mismatched or extra lines... 
FHFEFHEEEEE EEE EEE HEHEHE HHH 
... Succeeding context lines... 


If an end-of-file condition occurs or the maximum stack depth is reached during 
resynchronization, then one of the following messages will also appear: 


*** Nothing seems to match *** 
*** EOF on both files *** 

x** EOF on file 1 *** 

<*x EOF von. file’ 2 *** 


If both files are in synchronization, and both reach their end-of-file at the same time, 
then the following message will appear if any mismatches occurred: 


*** EOF on both files at the same time *** 
If both files match, then the following message is displayed: 


x** Files match *** 


Parameter errors are written to diagnostic output. 
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Status The following status codes may be returned to the Shell: 


0 “Files match 
1 Parameter or option error 
2 Files don’t match 
3 ‘Execution terminated 
Options -b Treat several blanks (spaces or tabs) as a single space, and ignore 


trailing blanks. 


(7D Redlrectan... 


Options 


CZ !gnore blanks (J Ignore trailing blanks 
C) Ignore case {) Show mismatched lines 


: Paes Columns |FRer5 


(] Fixed grouping 


CJ No tabs 
(C) No line numbers 


Command Line 
[ewes | 
Help 
Compare the tines of two TEXT files and writes their difference to the — —— 
eer [_campare__| 


-¢ col1-col2(,col1-col2| 
Compare only the columns col1 to col2 of each file. If the second 
column range is omitted, then the first range applies to both files; 
otherwise the first range applies to file and the second range 
applies to /tle2. If coll is omitted, 1 is assurned. If col2 is omitted, 
255 is assumed. 


Note: To use the -c option, tabs must be expanded. The tab setting 
is determined from the file’s tab value. (See also the -x option 
below.) 


-d depth Sets the maximum stack depth (size) for resynchronization, that is, 
how far out of synch the files can get before they’re no longer worth 
comparing. Depth is an integer value from 1 to 1000. The default is 
1000 if dynamic grouping is being used, and 25 for static (-s) 
grouping. 


-e context Up to the specified number of context lines are displayed before 
and after the mismatched or extra lines. Values of 1 to 100 are 
allowed. Context lines are shown only if they are equal in both files, 
so fewer than the specified number of lines may be shown. Note that 
this option is ignored if the -m option is specified. 
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-g groupingFacior 


-h width 


1 


-n 


“p 


-S 


-t 


-V 


-x 


Specifies the grouping factor, G. For dynamic grouping, -g specifies 
the minimum grouping factor, that is, the minimum number of 
lines that must match for the two files to be considered 
resynchronized. (This value must be at least 2, which is the default.) 
If the -s (static) option is used, -g specifies a fixed grouping factor. 
(Values are from 1 to 1000; the default is 3.) 


Display mismatches in the horizontal format. Only a portion of 
each mismatched line is displayed side by side. Width is a number 
from 70 to 255 that controls the number of characters displayed in 
each portion by specifying the total display line width. 


Ignore case differences (convert all lines to lowercase before 
comparing them). The default is case sensitive. 


Suppress the display of mismatched and extra lines. Only the 
mismatch messages and Shell editor commands to select the 
mismatches are displayed. The default is to display the mismatched 
and extra lines along with the messages. This option is ignored if the 
-h option is specified. 


Do not write any messages to standard output if both files match. 
Write Compare’s version information to diagnostic output. 


Static (fixed) grouping factor. The grouping factor is set with the 
-g option. 


Ignore trailing blanks (spaces or tabs). This is a subset of the 
-b option. 


Display differences between two files in a format that allows output 
lines to be cut and pasted into a source file. 


Suppress tab expansion. Normally, except when the -b option is 
used, tabs are expanded into spaces. The tab value is determined 
from the file’s tab setting (a resource); if there is no setting, 4 is 
used. 


Caution: This option can cause stacked lines to be displayed 
incorrectly if the files contain tabs. Also, the -c option should not 
be used with -x, because -c depends on the true columns as 
displayed with tabs expanded. 


Note: All comparison criteria that affect the individual lines before comparison— 
column range (-c), blanks compression (-b), and case conversion 

(-I)—are applied to those lines before they are stacked. Thus when the lines are 
displayed, they’ll be shown in their modified form. 
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Examples 


Limitations 


See also 


Compare File File.bak > Mismatches 


Compares File and File.bak, writing the results to the file Mismatches. No options are 
specified, so dynamic grouping is used, blanks are retained, tabs are expanded into 
spaces, and matching is case sensitive. 


Compare File.old.§ File.new.§ 


Compares the selected portions of the two windows and writes out the results. 


Compare can handle text files with a maximum line length of 255 characters. 


The text files compared should be fewer than 9999 lines long, because the displays are 
formatted based on four-digit line numbers. 


Equal command (Equal is a quicker command that tells you whether files are 
different, but stops at the first byte at which they differ). 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Option 


Confirm—display confirmation dialog box 
Confirm [ -t] [message...] 


Displays a confirmation dialog box with OK and Cancel buttons and the prompt 
message. There is no output to this command—the result of the dialog is returned in 
the {Status} variable. 


Note: Because Confirm returns a nonzero status value to indicate that No or Cancel 
was selected, a script should set the Shell variable {Exit} to zero before executing the 
Confirm command. (This step is necessary because the Shell aborts script processing 
when a nonzero status value is returned and {Exit} is nonzero.) 


Built-in. 

Reads standard input for the message if no parameters are specified. 
None. 

Errors are written to diagnostic output. 


The Confirm command may return the following status values: 


0 The OK button was selected 

1 Syntax error 

4 The Cancel button was selected 

5 The Cancel button was selected in a three-way dialog box—see the -t option 


Note: In the context of a two-button dialog, Cancel means the same thing as No; OK 
means Yes. 


-t Display a three-way confirmation dialog box, which includes Yes, 
No, and Cancel buttons. In this case, 4 means No and 5 means 
Cancel. 
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Examples Set Exit 0 
Confirm “Replace files with the same name? " 
If (Status} == 0 
Duplicate -y Source:* Destination: 
End 
Set Exit 1 


The following confirmation dialog box will be displayed: 


Replace files with the same name? 


If you select the OK button, the Duplicate command will be executed. 
The following script makes use of a three-way confirmation dialog box: 


Set Exit 0 

Set list ™ 

For file In ‘files -t TEXT’ 
Confirm -t “Print file {file}?" 
Set SaveStatus (Status} 


Continue If ({SaveStatus}) == 4 # No 
Break If (SaveStatus} == # Cancel 
Set list "{list} '{file}'" # Yes 


End If "{list}" | =." 
Print {PrintOptions} (list} 

End 

Set Exit 1 


This example prints selected TEXT files in the current directory. For each file, it 
displays a dialog box with three choices (Yes, No, and Cancel). Selecting Yes prints 
the file. If you select No, the Continue command causes this file to be skipped, but 
processing continues with the next file in the list. If you select Cancel, the Break 
command causes the For loop to be terminated, ending the question-and-answer 
session. The filenames are saved in the variable {list}, and printed following the loop. 


See also Alert and Request commands. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 


Continue—continue with next iteration of For or Loop 
Continue [ If expression ] 


If expression is nonzero, Continue terminates this iteration of the immediately 
enclosing For or Loop command, and continues with the next iteration. (Null strings 
evaluate to zero.) If the “If expression” clause is omitted, the Continue is 
unconditional. If no further iterations are possible, the For or Loop is terminated. 
(For a definition of expression, see the Evaluate command.) 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


Continue may return the following status values: 


0 No errors 
-—3 Error in parameters, or Continue not within For...End or Loop...End 
-5 Invalid expression 


None. 


Set Exit 0 

Set list "" 

For file In ‘files -t TEXT 
Confirm -t “Print file {file}?" 
Set SaveStatus {Status} 


Continue If {SaveStatus} == # No 
Break If (SaveStatus} == 5 # Cancel 
Set list "{list} '{file}'" # YesEnd 
Print {PrintOptions} {list} 
Set Exit 1 


In this example, the Continue command is executed if the user selects No (status 
value 4). The Continue causes the current file to be skipped, but processing continues 
with the next file in the list. 


(For a full explanation of this example, refer to the Confirm command.) 


For, Loop, Break, and If commands. 
Evaluate command, for a description of expressions. 
“Structured Commands” in Chapter 5. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Option 


Examples 


See also 


Copy—copy selection to Clipboard 
Copy [-c count] selection { window } 


Finds selection in the specified window and copies it to the Clipboard, replacing the 
previous contents of the Clipboard. If no window is specified, the command operates 
on the target window (the second window from the front). It’s an error to specify a 
window that doesn’t exist. 


For a definition of selection, see “Selections” in Chapter 6; a summary of the 
selection syntax is contained in Appendix B. 


Note: To copy files, use the Duplicate command. 
Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


Copy may return the following status values: 


0 At least one instance of the selection was found 
1 Syntax error 
2 Any other error 


-c count For a count of 7, find and copy the nth instance of selection. 


Copy § 


Copies the current selection to the Clipboard. This command is like the Copy 
command in the Edit menu, except that the action takes place in the target window. 


Copy /BEGIN/:/END/ 


Selects everything from the next BEGIN through the following END, and copies this 
selection to the Clipboard. 


Cut and Paste commands. 
“Selections” in Chapter 6 and Appendix B. 


Copy I-47 


Syntax 


Description 


Type 


input 


Output 


Diagnostics 


Status 


Options 


Examples 


Note 


Count—count lines and characters 
Count [-1 ] [-c] [file...] 


Counts the lines and characters in its input, and writes the results to standard output. If 
no files are specified, standard input is read. If more than one file is specified, 
separate counts are printed for each file, one per line, preceded by the filename, and 
a total is printed following the list. 


Tool. 

Standard input is read if no files are specified on the command line. 
Line and character counts are written to standard output. 

Errors are written to diagnostic output 


Count may return the following status values: 


0 No errors 
1 Error in parameters 
2 Unable to open input file 


-l Write only the line counts. 


-C Write only the character counts. 


Count MakeFile.c Count.c 


Displays line counts and character counts in the form 


MakeFile.c 43 981 
Count.c 153 3327 
Total 196 4303 


Files {| Count -l 


Display the total number of files and directories in the current directory. 


Count -l § 
Display the number of lines selected in the target window. 


The source code for Count is included in the CExamples folder, in the file Count.c, as 
part of MPW C. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


CreateMake—create a simple makefile 


CreateMake [-Application | -Tool | -DA] program file... 


Create a simple makefile for building the specified program. The program parameter 
is the name of the program. Makefile program.make is created. The list of files 
includes both source and library files. Source files may be written in any combination 
of assembly-language (suffix “.a”), C (“.c”), Pascal (*.p”), and/or Rez (“.r”). 


Library files (suffix “.o”) may also be specified. The program will be linked with these 
files. CreateMake automatically links with the library files listed below. It is not 
necessary to specify these files as parameters to CreateMake. 


Makefiles for building applications (the default), tools, and desk accessories may be 
created. 


CreateMake generates commands that link the program with the following set of MPW 
libraries: 


Q Inside Macintosh Interfaces 
{Libraries}Interface.o 

QO Runtime support—one of the following: 
{Libraries}Runtime.o # no C object files 
{CLibraries}CRuntime.o —_ # any C object files 

OG C Libraries—if any source is in C 
{CLibraries}StdCLib.o 
{CLibraries}CSANELib.o 
{CLibraries}Math.o 
{CLibraries}CInterface.o 

QO Pascal Libraries—if any source is in Pascal 
{PLibraries}PasLib.o 
{PLibraries}SANELib.o 

O For tools: 
{Libraries}ToolLibs.o 

O For desk accessories: 
{Libraries}DRVRRuntime.o 


CreateMake does not include dependencies on include files and USES files in the 
makefile. Libraries other than those listed above are not included in the Link 
command generated by CreateMake, unless specified as parameters. CreateMake is 
used to implement the Create Build Commands item in the Build menu. 


Script. 


None. 
None. 


Errors are written to diagnostic output 
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Status 


Options 


Example 


See also 
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The following status values may be returned: 


0 Successful completion 
1 Parameter or option error 


-application Create build commands for building an application. This is the 


-tool 
-da 


CreateMake 


default. 
Create build commands for building a tool. 
Create build commands for building a desk accessory. 


-Tool Count Count.c Stubs.a Count.r 


Creates the makefile Count. make containing commands for building tool Count from 
source files Count.c, Stubs.a, and Count.r. The makefile will be similiar to the 


following: 

# File: Count .make 

# Target: Count 

# Sources: Count.c Stubs.a Count.r 

# Created: Monday, February 9, 1987 3:04:44 PM 


Count.c.o f Count.make Count.c 
C Count.c 
Stubs.a.o f Count.make Stubs.a 
Asm Stubs.a 
Count ff Count.make Count.r 
Rez ~append Count.r -o Count 
Count ff Count.make Count.c.o Stubs.a.o 


Link 


-w -t MPST -c 'MPS '' @ 
Count.c.o @ 

Stubs.a.o @ 
"(Libraries)"Interface.o @ 
"(CLibraries}"CRuntime.o @ 
"{CLibraries}"StdCLib.o @ 
"(CLibraries}"CSANELib.o @ 
"(CLibraries}"Math.o @ 
"(CLibraries}"CInterface.o @ 
"(Libraries}"ToolLibs.o @ 
~o Count 


BuildMenu and BuildProgram commands. 


“Building a Program: An Introduction” in Chapter 2. 


CreateMake 


Cut—copy selection fo Clipboard and delete if 
Syntax Cut [-c count] selection [ window) 


Description Finds selection in the specified window, copies its contents to the Clipboard, and 
then deletes the selection. If no window is specified, the command operates on the 
target window (the second window from the front). It’s an error to specify a window 
that doesn’t exist. 


For a definition of selection, see “Selections” in Chapter 6; a summary of the 
selection syntax is contained in Appendix B. 


Type Built-in. 
Input None. 
Output None. 


Diagnostics Errors are written to diagnostic output. 


Status Cut may return the following status values: 


0 At least one instance of the selection was found 
1 Syntax error 
zZ Any other error 


Option -c count Find and cut count instances of selection. 


Examples Cut § 


Cuts the current selection in the target window. (This is the same as the Cut menu 
item, except that it operates on the target window rather than the active window.) 


Cut /BEGIN/:/END/ 


Selects everything from the next BEGIN through the following END, copies the 
contents of the selection to the Clipboard, and then deletes the selection. 


See also Clear, Copy, and Paste commands. 
“Selections” in Chapter 6 and in Appendix B. 
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Syntax 


Description 


CvtObj—convert Lisa Workshop object files 
to MPW object files 


CvtObj [-n namesFile} [ -o outputFile] [-p] LisaObjFile 


Converts a Lisa object file (OBJ file) to the Macintosh object format (.0 file). This 
command is for Lisa Workshop users who have old object files but no source files that 
can be ported to the MPW system. 


CvtObj supports object files produced by the Lisa Pascal Compiler, the Green Hills C 
Compiler, and the TLA Assembler that were targeted to the Macintosh runtime 
environment. Object files produced by other compilers have not been tested, but 
should work. The program should not be used to convert object files targeted for 
execution on Lisa. 


Object files produced by the Lisa Pascal Compiler must have been compiled with the 
Macintosh code generation option, $M+. Object files produced by the Green Hills C 
Compiler must have been compiled with the default code generation option, that is, 
the -lisa option must not have been specified. Assembler code produced by the TLA 
Assembler should conform to the guidelines outlined in the Using Assembly Language 
chapter of Inside Macintosh. 


CvtObj detects and rejects a number of Lisa object record types. If this happens, 
CvtObj generates a fatal error message (“Can’t handle ...”), and terminates without 
producing an output file. However, CvtObj cannot detect and reject all object files 
targeted for execution on the Lisa, especially Pascal and TLA Assembler files. 


The Lisa Workshop tools support only 8-character case-insensitive (shifted to 
uppercase) external identifiers. The MPW Compilers support variable-length, case- 
sensitive external identifiers. (The MPW Pascal Compiler still defaults to upshifting 
Pascal identifiers, primarily for language compatibility, portability of sources, and 
ease in providing both C and Pascal interfaces to the Macintosh ROM routines.) 
CvtObj provides the -n option for substituting names, so that old object files can be 
properly linked with new object files. The -m option specifies a “names” file, which 
controls name substitution. 


Data Initialization: In general, CvtObj automatically matches the Lisa object file 
semantics with those of the Macintosh. However, data initialization records are more 
difficult to handle. With the Lisa tools, data areas were often defined with differing 
lengths, partial contents in different files, and so on. The underlying model was 
Fortran-named common areas, with multiple initialization sources. On the 
Macintosh, the default is to use only the first definition of a data module. In order to 
match the Macintosh default as closely as possible, CvtObj does not emit a defining 
instance of a data area unless initialization values are seen. 


For C data areas that need to be initialized to zero, this behavior can result in Linker 
error messages reporting that the data area names are “unresolved external 
references.” If the references come from a file produced by CvtObj, then the define 
directive can be used in a “names” (-n) file to request CvtObj to emit a defining 
instance—this should result in a proper size definition for the data area, unless the 
data area was defined elsewhere as larger. 


Note: The DumpObj command can be useful in tracking down and fixing anomalies 
in external names and data area definitions when using CvtObj. 
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Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 


See also 


Tool. 


None. 


If no -o option is specified, output is written to the file CvtObj.out.o. 


Errors and warnings are written to the diagnostic file. Progress information is also 
written to the diagnostic file (with the -p option). 


The following status values may be returned: 


0 No problem 
2 Fatal error 
3 User interrupt 


-n namesFile Create name-conversion file. In this text file, lines that begin with a 
space or tab are interpreted as name substitution lines; the first 
name is the old name, the second name is the new name. (See 
“Examples” below.) All occurrences of the old name are replaced 
with the new name. Lines that begin with the word define, followed 
by an entry name, create a global data module for that name. 


-O ouiputFile Direct output to outputFile. The default output filename is 
CvtObj.out.o. 


-p Write progress information to diagnostic output. 


CvtObj -o MyFile.o MyLisaFile.OBJ 


Converts file MyLisaFile.OBJ, placing the output in MyFile.o. 


CvtObj -n NewNames -o MyFile2.o0 MyLisaFile2.OBJ 


Converts file MyLisaFile2.OBJ, placing the output in MyFile2.0, and applying the 
name translations specified in NewNames. The NewNames file might contain the 
following: 


ACLOSEOUT CloseOutput 
ADRAWROUN DrawRoundFigure 
AFOO2 Foo2 

define FOO 


where A indicates a leading space or tab character. 


TLACvt, Link, and DumpObj commands. 
Appendix F. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 
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Date—write the date and time 
Date [-a | -s] [-d! -t] 

Writes the current date and time to standard output. 
Built-in. 

None. 

The date is written to standard output. 

Errors are written to diagnostic output. 


Date may return the following status values: 


0 No error 
1 Syntax error 


-a Abbreviated date. Three-character abbreviations are used for the 
month and day of the week. For example, Thu, Aug 29, 1987. 


-d Write the date only. 


-S Short date form. Numeric values are used for the date. The day of 
the week is not given. For example, 8/29/87 (month/day/year). 


-t Write the time only. 


Date 


returns the date in the form 


Friday, February 14, 1986 10:34:25 PM 


Date ~-a 


returns 


Fri, Feb 14, 1986 10:34:25 PM 


Date -s -d 
returns 


2/14/86 


Syntax 


Description 


Type 
Input 
Output 


Diagnostics 


Status 


Options 


Example 


Delete—delete files and directories 
Delete [-y | -n | -c] [-i] [-p] name... 


Deletes file or directory name. If name is a directory, then name and its contents 
(including all subdirectories) are deleted. 


Before deleting directories, a dialog box will request confirmation for the deletion. 
Use the -y, -n, or -c options in scripts to avoid this interaction. Be sure to see the 
warning at the end of this section. 


Built-in. 
None. 
None. 


Errors and warnings are written to diagnostic output. Progress and summary 
information is also written to diagnostic output if the -p option is specified. 


The following status values may be returned: 


0 All specified objects were deleted (except for any directories skipped with the -n 
option) 

1 Syntax error 

2 An error occurred during the delete 

4 Cancel was selected or implied by the -c option 


-i Ignore errors (that is, do not print messages, and return a status 
value of 0). 
-n Answer “no” to any confirmation dialog that may occur, skipping 


the delete for any directories encountered. 
-p List progress information as the delete takes place. 


-y Answer “yes” to any confirmation dialog that may occur, causing 
any directory encountered to be deleted. 


-C Answer “cancel” to any confirmation dialog that may occur, 
causing the delete to stop when a directory is encountered. 


Delete HD:MPW:s.c 


Deletes ail items in the MPW folder that end in “.c”. (Recall that the Shell first 
replaces the parameter “=.c” with a list of filenames matching the pattern—the Delete 
command then deletes each of these files.) 


Delete -55 


Warning 


See also 


H-56 


Beware of potentially disastrous typing mistakes such as the following: 


Delete = .c 


Note the space after “="—this space causes “=” and “.c” to be treated as two separate 
parameters. In this case, Delete would delete ail files in the current directory, and 
also attempt to delete a file named “*.c”. 


Also note that the following command deletes everything: 


Delete =; 


That is, the filename pattern =: expands to the names of ail volumes online 
(including the startup volume!). 


When deleting files en masse, it’s a good practice to use the Echo command to verify 
the action of the filename generation operators; for example, 


Echo #,.c 


Clear command (for deleting selections). 


“Filename Generation” in Chapter 5. 


Delete 


DeleteMenu—delete user-defined menus and items 


Syntax DeleteMenu [ menuName [ itemName)] 

Description Deletes the user-defined item itemName, in the menu menuName. If ttemName is 
omitted, all user-defined items for menuName are deleted. 

Caution: If ttemName and menuName are both omitted, all user-defined items are deleted. 
Menu items that haven’t been added with AddMenu can’t be deleted with 
DeleteMenu. 

Type Built-in. 

Input None. 

Output None. 


Diagnostics Errors are written to diagnostic output. 


Status DeleteMenu may return the following status values: 


0 No errors 
1 Syntax error 
2 Other errors 


Options None. 


Example DeleteMenu File 


Deletes all user-defined items from the File menu. 


See also AddMenu command. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


DeRez—Resource Decompiler 
DeRez [ option... ] resourceFile (resourceDescriptionFile... ] 


Creates a text representation (resource description) of the resource fork of 
resourceFile, according to the resource type declarations in the resource description 
file(s). The resource description is written to standard output. 


A resource description file is a file of type declarations in the same format as that 
used by the Resource Compiler, Rez. The type declarations for standard Macintosh 
resources are contained in the files Types.r and SysTypes.r, contained in the 
{RIncludes} folder. If no resource description file is specified, the output consists of 
data statements giving the resource data in hexadecimal form, without any 
additional format information. 


If the output of DeRez is used as input to Rez, with the same resource description files, 
it produces the same resource fork that was originally input to DeRez. DeRez is not 
guaranteed to be able to run a declaration backwards—f it can’t, it produces a data 
statement instead of the appropriate resource statement. 


DeRez ignores all include (but not #include), read, data, and resource 
statements found in the resourceDescriptionFile. (It still parses these statements for 
correct syntax.) 


For the format of resource type declarations, see Chapter 6 and Appendix D. 
Tool. 


Standard input is never read. DeRez requires a resource file as input. You may give 
optional formatting information by specifying one or more resource description 
files. 


For all input files on the command line, the following search rules are applied: 
1. DeRez tries to open the file with the name specified “as is.” 
2. If rule 1 fails, and the filename contains no colons or begins with a 


colon, DeRez appends the filename to each of the pathnames - 
specified by the {RIncludes} variable and tries to open the file. 


A resource description is written to standard output The resource description 
consists of resource and data statements that can be understood by Rez. (See 
Chapter 8.) 


If no errors or warnings are detected, DeRez nuns silently. Errors and warnings are 
written to diagnostic output. 


DeRez may return the following status values: 


0 No errors 

Error in parameters 
Syntax error in file 
I/O or program error 


WN & 
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Options -clompatible] Generate output that is backward compatible with Rez 1.0. 


-d{efine] macrd=data | 
Define the macro variable macro to have the value data. If data is 
omitted, then macro is set to the null string—note that this still 
means that macro is defined. Using the -d option is the same 
as writing 
#define macro( data] 
at the beginning of the input. The -d option may be repeated any 
number of times. 


Derez Options 


File to decompile Types ———____—_-———_—, 
[ becom ile Ski 
Types Files... #INCLUDE Paths... | 


Width of decompiled strings 


| (J No warnings for redeclared types | 


| (Progress information | 


Preprocessor 
CJ Write Rez 1.0 compatible output I ri 


_O) Don't escape characters | 
| Gutput Error | | 

| 
ae) eases | 7 


Undefine 


{ Seowvs 


Help 
DeRez = the resource decompiler. This tool can decompile a resource file 
into a text representation suitable for Rez input. 


-e[scape] When this option is specified, characters that are normally escaped 
(such as: \Oxff are no longer escaped. Instead they are printed as 
extended Macintosh characters. (Note: Not all fonts have all the 
characters defined.) Normally characters with values between $20 
and $D8 are printed as Macintosh characters. With this option, 
however, all characters (except null, newline, tab, backspace, 
formfeed, vertical tab, and rubout) will be printed as characters, 
not as escape sequences. 


-i Lets you specify one or more pathnames to search for #include 
files. This option may be specified more than once. The paths will 
be searched in the order they appear on the command line. 


derez -i (mpw}myStuff: -i hd:tools... 


-m{axstringsize] n 


Set the maximum string size to 7; m must be in the range 2-120. This 
setting controls how wide strings will be in the output. 
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-only typeExpr [ UD1[:ID2)) | resourceName | 
Read only resources of resource type typeExpr. If an ID, range of 
IDs, or resource name is given, read only those resources for the 
given type. This option may be repeated. 


Note: typeExpr is an expression, so literal quotes (') might be 
needed. If an ID, range of IDs, or name is given, the entire option 
parameter must be quoted; for example, 

DeRez ~-only "'MENU'(1:128)" ... 

See also the “Examples” section below. 

Note: The -only option cannot be specified together with the -skip 
option. 


-only type A simpler version of the above option—no quotes are needed to 
specify a literal type as long as it starts with a letter. No escape 
characters or anything fancy is allowed. For example, 


DeRez -only MENU ... 
-p Display progress and version information. 
-rd Suppress warning messages if a resource type is redeclared. 


-s{kip] typeExpr [( ID1[: ID2)) | resourceName | 
Skip resources of type typeExpr in the resource file. For example, 
it’s very useful to be able to skip 'CODE' resources. typeExpr is an 
expression—see the note under -only. The -s option may be 
repeated any number of times. 


-si{kip] type A simpler version of the -s option—no quotes are needed to specify 
a literal as long as it starts with a letter. 


-u(ndef] macro Undefine the macro variable macro. This is the same as writing 


#fundef macro 


at the beginning of the input file. It is meaningful to undefine only 
the preset macro variables. This option may be repeated. 


Examples DeRez "{ShellDirectory}MPW Shell" -only MENU Types.r 


Displays all of the 'MENU' resources used by the MPW Shell. The type definition for 
'MENU' resources is found in the file Types.r. 


DeRez HD:0S:System SysTypes.r @ 
~only "'"DRVR' (d"\0x00Scrapbooko")" 


Decompiles the Scrapbook desk accessory in the copy of the System file that’s located 
in directory HD:OS:. (The type definition for 'DRVR' resources is found in the file 
SysTypes.r.) 


See also Rez and RezDet commands. 
Chapter 8. 
Type declaration files in RIncludes folder: 
O Types.r 
QO SysTypes.r 


O MPWTypes.r 
I-60 DeRez 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Option 


Examples 


See also 


Directory—set or write the default directory 
Directory [-q | directory] 


If specified, directory becomes the new default directory. Otherwise the pathname of 
the current default directory is written to standard output 


Note: To display a directory’s contents, use the Files command. 
Built-in. 
None. 


If no directory is specified, the default directory pathname is written to standard 
output. 


Errors are written to diagnostic output 


Directory may return the following status values: 


0 No error 
1 Directory not found, command aborted 


-q Don’t quote the pathname that is written to standard output. 
Normally, a directory name is quoted if it contains spaces or other 
special characters. 


Directory 


Writes the pathname of the current directory to standard output 


Directory HD:MPW:AExamples: 


Sets the default directory to the folder AExamples in the folder MPW on the volume 
HD. The final colon is optional. 


Directory Reports: 


Sets the default directory to the volume Reports. Note that volume names must end in 
a colon. 


Directory :Include:Pascal: 


Sets the default directory to the folder Pascal in the folder Include in the current 
default directory. 


“File and Window Names” in Chapter 4. 


Files, NewFolder, and SetDirectory commands. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


DirectoryMenu—create the Directory menu 
DirectoryMenu [directory...] 


Creates the Directory menu shown below. The optional directory... 
parameter specifies the initial list of directories that appears in the menu. The 
menu items are described in Chapter 3. 


Directory 
Show Directory 
Set Directory... 


HD :MPW:AExamples: 
HD :MPW:CExamples: 
HD :MPW:PExamples: 
HD :MPW: 


The lower section of the Directory menu contains a list of directories. Initially 
this list consists of the parameters to DirectoryMenu. As other directories 
become the current directory (using the Set Directory menu item or the 
SetDirectory command) they are added to the list. 


Script. 

None. 

None. 

Errors are written to diagnostic output. 
Status value 0 is always returned. 
None. 


DirectoryMenu * (Files -d -i "(MPW}"sExamples™) 2 Dev:Null* ‘Directory’ 


Creates the Directory menu. Directories in directory "{MPW}" that match the 
pattern =Examples= will be included in the Directory menu, along with the 
current directory. 


This DirectoryMenu command should be included in your UserStartup file to 
install the Directory menu. You might replace the Examples directories and 
the default directory with your favorite list of directories. 
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Syntax 


Description 


Type 
Input 
_ Output 


Diagnostics 


Status 


Options 


DumpCode—write formatted resources 
DumpCode [ option... ] resourceFile 


Disassembles object code that is stored in resources such as 'CODE', 'DRVR', and. 
'PDEF'. DumpCode reads from the resource fork of the specified file, and writes the 
formatted assembly code to standard output. The default formatting convention is to 
disassemble the code, and to display the corresponding bytes in hexadecimal and 
ASCII. 


The default behavior of DumpCode is to dump all the 'CODE' resources from a 
program file. The -rt option can be used to dump resources of other types, such as 
drivers and desk accessories. ' 


Some conventions about executable code resources are built into DumpCode, and 
affect the formatted output in special ways: 


CG 'CODE' resources with ID 0 are formatted as a jump table Cunioaded format). 


QO Other 'CODE' resources have information about jump table entries in the first four 
bytes. 


O 'DRVR' resources have a special format at the beginning of the resource. 


In addition, you can direct DumpCode to give a symbolic dump of data initialization 
descriptors and initial values. 


Tool. 
None. 
DumpCode writes formatted resources to standard output. 


Errors and warnings are written to diagnostic output. Progress information can also 
be written to diagnostic output (with the -p option). 


DumpCode may return the following status values: 


0 No problem 
2 Fatal error 
3 User interrupt 


Note: Numeric values for options can be specified as decimal constants, or as hex 
constants preceded by a “$”. 


-d Suppress the disassembly and dumping of code. (The default is to 
disassemble the code.) 


This option is useful in producing a small output file, and looking at 
just the resource names, sizes, and resource header information. It 
is also useful when just some specialized information is desired, 
such as the jump table or data descriptors. 


-di Suppress display of data initialization code. 
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Example 


See also 
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-h Suppress the writing of header information, such as resource 
relative locations, hexadecimal and ASCII equivalents, and so on. 
The default is to produce this type of header information. 


This option is useful in producing output that can be edited and 
submitted to the Assembler for reassembly. 


jt a Suppress formatting of jump table. Only summary information for 


the jump table is given. (The default is to format the jump 
table unless one of the options -s, -rt, -n, or -jt is specified.) 


-n Write only the resource names associated with resources. This 
option is useful for finding segments or desk accessories by name. 


-p Write progress information (filenames, resource names, IDs, and 
' sizes) to diagnostic output. 


-r byteill,byteN] 
- Limit the disassembly of code to the range bytel...byteN. The 
default is to disassemble all bytes in a segment. If byteN is omitted, 
then the rest of the segment is disassembled. 


-rt typel=ID] Dump only the single resource with type type and ID number JD. If 
ID is omitted, then all resources of the specified type are dumped. 


-S resourceName . 
Dump only the single resource named resourceName. 


DumpCode Sample > SampleDump 


Formats the 'CODE' resources in the file Sample, writing the output to the file 
SampleDump. The output has this format: . 


File: sample, Resource 3, Type: CODE, Name: _DataInit 
Offset of first jump table entry: $00000018 . 


Segment is $000000D2 bytes long, and uses 1 jump table entry 


000000: 48E7 FFFO oe > Cena MOVEM.L DO-D7/A0~-A3,-(A7) 
000004: 4247 ‘BG' CLR.W D7 

000006: 4EAD 0032 'N..2' JSR $0032 (A5) 

OOOOOA: 2218 ae aes _ MOVE.L (AO) +,D1 

etc. 


DumpObj command. 


“Data Initialization” under the CvtObj command for a description of data 
intialization calls. 


“The Jump Table” in the Segment Loader chapter of Inside Macintosh, for a 
description of the jump table. 


- Appendix F, “Object File Format.” 
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Syntax 


Description 


Type 
Input 


Output 
Diagnostics 


| Status 


Options 


DumpObj—write formatted object file 
DumpObj [ option... ] objectFile 


Disassembles. object code that is stored in the data fork of an object file. By © 
convention, object files end in the suffix “.o”. In addition, the object file must have 


type ‘OBJ. 


Tool. 
DumpObj does not read standard input. 


DumpObj writes formatted object file records and disassembled code to standard 
output. 


Errors and warnings are written to diagnostic output. Progress information is also 
written to diagnostic output with the -p option. 


DumpObj may return the following status values: 


0 No problem 
2 Fatal error 
3. _-User interrupt 


-d Suppress disassembly of code and display of data. The default is to 
disassemble code and to display data in hexadecimal and ASCII. 


-i Suppress substitution of names for IDs. The default is to preread the 
. entire file, processing the Dictionary records, and then to show 
names in place of ID numbers. 


This option is useful in examining an object file up to the point 
where an object file format error has been reported by Link or Lib; 
that is, it suppresses the preread, which is also likely to fail. 
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-h . Suppress printing of header information on code lines. Header 
information includes the offset of the code and the code bytes in 
hex and ASCII. The default is to print header information. 


This option is useful in producing code that can be edited and 
submitted to the Assembler for reassembly. 


DumpObj Options 


Cl Progress Info Modules: 
C1 No headers 


C] Use {Ds 
pucous CJ File Locations 
C] Names only 
Error 
(J No disassembly 
Byte Range 


Command Line : 
ince ae ee Ne 
Help : 
Dumped] is used to display the contents of MP'W object files a 


-l Print file locations of object records. The default is not to print 
these locations. 


This option is useful in debugging compilers and assemblers, 
particularly when debugging code used to generate Pad records to 
assure alignment. (See Appendix F.) 


-m name Dump a particular module. If mame is an entry point, then the 
module containing mame is dumped. Other options that control 
format still have an effect. 


Note: name is case sensitive, as are all object file identifiers. 


-n Print names only. When this option is specified, only the -p option 
has an effect. 
This option is useful in determining which names are defined in an 
object file, particularly when there appears to be a discrepancy in 
spelling, capitalization, or length of identifiers. 


-p | Write progress information (such as the name of the file being 
dumped and the version of DumpObj) to diagnostic output. 


-r byteil,byteN) 
Limit the disassembly of code to the range bytel1...byteN. The 
default is to disassemble all bytes in a segment. If byteN is omitted, 
then the rest of the segment is disassembled. 
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Example 


See also 


DumpObj} Sample.p.o >SampleDump 


Formats the file Sample.p.o and writes its contents to the file SampleDump. This 
output has the following format: 


Dump of file sample.p.o 
First: Kind 0 Version 1 
Dictionary: FirstId 2 
2: Main 
Pad 
Module: Flags $00 ModuleId 1 SegmentId Main 
Content: Flags $00 
Contents offset 0000 size OO6A 


000000: 4ES56 FFFE 'NV..! LINK AG, #SFFFE 
000004: 2F07 Fee MOVE.L D7,-(A7) 
000006; 42A7 "BY! CLR.L ~(A7) 
000008: 3F3C 0080 '2<,,! MOVE. W #50080, -(A7) 
ete. 


For more information, see Appendix F. 


DumpCode command. 
Appendix F, “Object File Format.” 


DumpObj 
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Syntax 


Description 


Type 
Input 
Output 


Diagnostics. 


Status 


Duplicate—duplicate files and directories 
Duplicate [-y | -n | -c] [-di-r] [-p] name.. targetName 


Duplicates name to targetName. (Name and targetName are file or directory 
names.) If targetName is a file or doesn’t exist, then the file or directory name is 
duplicated and named targetName. If targetName is a directory, then the objects 
named are duplicated into that directory. df more than one name is present, 
targetName must be a directory.) Created objects are given the same creation and 
modification dates as their source. 


If a directory is duplicated, then its contents (including all subdirectories) are also 
duplicated. No directory duplicated can be a parent of targetName. 


Name can also be a volume; if targetName is a directory, then name is copied into 


_targetName. 


A dialog box requests a confirmation if the duplication would overwrite an existing file 
or folder. You can use the -y, -n, or -c option in command files to avoid this 
interaction. 


Built-in. 
None. 
None. 


Errors are written to diagnostic output. Progress and summary information is written 
to diagnostic output if the -p option is specified. 


The following status values may be returned: 


0 All objects were duplicated 

1 Missing or inaccessible parameters 

2 An error occurred 

4 Cancel was selected or implied from the -c option 
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Options 


Examples 


Limitation 


See also 


-y Answer “yes” to any confirmation dialog that occurs, causing 


conflicting files or folders to be overwritten. 


-n Answer “no” to any confirmation dialog that occurs, skipping files 


or folders that already exist. 


-C Answer “cancel” to any confirmation dialog that occurs, causing 


the duplication to stop when a name conflict is encountered. 


-d Duplicate the data fork only. If targetName is an existing file, its 
data fork is overwritten and its resource fork remains untouched. 


-r _ Duplicate the resource fork only. If targetName is an existing file, 
its resource fork is overwritten and its data fork remains untouched. 


-p List progress information. 


Duplicate Aug86 "Monthly Reports" 


Assuming “Monthly Reports” is’an existing directory, duplicates the file Aug86 into 


that directory. 


Duplicate Filel Folderl "Backup Disk:" 
Duplicates Filel and Folderl (including its contents) onto Backup Disk. 


Duplicate -y Filel File2 
Duplicates Filel to File2, overwriting File2 if it exists. 


pusricars Diskl:= HD:Files: 
Duplicates all of the files on Disk1 into the directory HD:Files. 


Duplicate Diskl: HD:Files: 
Duplicates all of Disk1 (as a directory) into HD:Files. 


Duplicate doesn’t recognize folders on non-HFS disks. 


Move and Rename commands. ‘ 
“File and Window Names” in Chapter 4. 


“Filename Generation” in Chapter 5. 


Duplicate 
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Syntax 


Description 


Type 

Irput 
Output 
Diagnostics 
Status 


Option 


Examples 


See also 


“1-70. Echo 


Echo—echo parameters 
Echo [-n] [ parameters... ] 


Writes its parameters, separated by spaces and terminated by a return, to standard 
output. If no parameters are specified, only a return is written. 


Echo is especially useful for checking the results of variable substitution, command 
substitution, and filename generation. 


Built-in. 


None. 


Parameters are written to standard output. 
None. 
Status value 0 is always returned. 


-n | Don’t write a return following Echo’s parameters (that is, the 
insertion point remains at the end of the output line). The -n isn’t 
echoed. 


Echo "Use Echo to write progress info from scripts." 
Use Echo to write progress info from scripts. 


The Echo command above writes the second line to standard output. 


Echo {Status} 


Writes the current value of the {Status} variable; that is, the status of.the last command 
executed. ; 


Echo *=,a 


Echoes the names of all files in the current directory that end with *.a”. (This might 


be useful as a precaution before executing another command with the argument 


“=.a”.) 
Echo <n > EmptyFile 


If EmptyFile exists, this command deletes its contents; if the file doesn’t exist; it is 
created. . . 


Parameters and Quote commands. 


Syntax : 


Description 


Type 

Input 
Output 
Diagnostics 


Status 


Option 


Examples 


See also 


Eject—eject volumes 


Eject [-m] volume... 


Flushes the volume, unmounts it, and then ejects it, if it is a floppy disk. A volume 


name must end with a colon (:). If volume is a number without a colon, it’s 
interpreted as a drive number. 


Note: If you unmount the current volume (the volume containing the current 


directory), the boot volume becomes the current volume. You can keep the volume 
mounted with the -m option. (See the File Manager chapter of Inside Macintosh.) 


Built-in. 


None. 


None. 


Errors are written to diagnostic output. 


The following status values may be returned: 


0 ‘The disk was successfully ejected 


1 Syntax error 
2 An error occurred 


-m Leave the volume mounted. 


Eject Memos: 


Ejects (and unmounts) the disk titled Memos. 


Eject 1 
Ejects and unmounts the disk in drive 1 (the internal drive). 


Eject fst 
Ejects and unmounts all volumes. 


Mount, Unmount, and Volumes commands. 


Eject 
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Entab—convert runs of spaces to tabs 
Syntax Entab [ option...] [ file... ] 


Description Copies the specified text files to standard output, replacing runs of spaces with tabs. 
The default behavior of Entab is to do the following: 


1. Detab the input file, using the file’s tab setting (a resource saved with the file 
by the Shell editor), or 4 if there is none. You can override this “detab” value with 
the -d option. 


2. Then entab the file, setting tab stops every 4 spaces. You can specify another tab 
setting with the -t option. The entabbed output file looks the same as the original 
file(s), but contains fewer characters. 


Options are also provided for controlling the processing of blanks between quoted 


Strings. 
Type Tool. 
Input | If no filenames are specified, standard input is processed. 
Output All files are written to standard output. 


Diagnostics Parameter errors and progress information (with the -p option) are written to’ 
diagnostic output. 


Status The following status codes may be returned to the Shell: 


0 Normal termination | 
1 Parameter or option error 
2 Execution terminated 
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Options 


Example 


Warning 


Limitations 


See also 


-d tabSetting Override the input file’s default tab setting with tabSetting. This 
option is useful for detabbing non-MPW files. 


Note: Entab always detabs the input file, using the file’s tab setting, 
or 4 if there is none. For MPW files, specifying a -d option would 
override the file’s own tab setting, leading to incorrect results if a 
different value were used. 


-l quote... Specify a list of left quote characters. Quote... is a string of one or 
more nonblank characters. If -l is specified, then -r must also be 
specified. Single quotes (') and double quotes (") are assumed as 
the default quoting characters. 


-n Treat all quotes as “normal” characters—entab the file, replacing 
runs of spaces embedded in quoted strings with tabs. 


Caution: This option should not be used when entabbing program 
source files. If this option is used, the -q, -1, and -r options are 


ignored. 
-p _ Write version and progress information to diagnostic output. 
-q quote... Specify a list of characters to be used as both left and right quotes. 


Quote... is a string of one or more nonblank characters. This is the 
default option; single quotes (') and double quotes ") are assumed 
as the quoting epataces: 


-r quote... Specify a list of right quote characters. Quote... is a string of one or 
more nonblank characters. If -r is specified, then -1 must also be 
specified. 


Note: Entab does not check that a particular left quote character 
matches a particular right quote character. 


-t tabSetting Set the output file’s tab setting to tabSetting. If the -t option is 
omitted, 4 is assumed for the tab setting. If you specify a tab setting 
of 0, no tabs are placed in the output. Thus -t 0 may be used to 

- completely detab input files. 


Caution: If you specify the -q, -l, or -r option, then you should quote the entire string 
parameter to these options (otherwise, the Shell may misinterpret special characters 
in the parameter string). 


Entab -t 2 Example.p > CleanExample.p 


Detabs the file Example.p (using the file’s default tab setting), re-entabs it with a tab 
setting of 2, and writes the resulting output to CleanExample.p. 


Beware of command formats such as 


Entab Foo > Foo 


Entab does not take into account embedded formatting characters except for tab 
characters. Thus backspace characters may cause incorrect results. 


' The maximum width for an input line is 255 characters. 


Tab command. 
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-Equal—compare files and directories 
Syntax _ Equal [ option...] name... targetName 


Description Compares name to targetName. By default, Equal makes no comment if files are the 
same; if they differ, it announces the byte at which the difference occurred. When 
comparing directories, the default condition is to report all differences, including 
files not found—the -i option ignores files in targetName that are not present in 
name. 


If targetName is a file, every name must also be a file. The specified files are 
compared with targetName. | 


If targetName is a directory and name is a file, Equal checks in targetName for the 
file name and compares the two files. That is, the command 


Equal Filel Dirl 
compares Filel with :Dir1:File1. 


If more than one name is specified, Equal compares each name with the 
corresponding file or directory in targetName . All subdirectories are also 
compared. The command 


Equal Filel Dirl Dir2 
compares File1 with :Dir2:Filel1 and then compares Dirl with :Dir2:Dir1. 


If targetName is a directory, name is a directory, and only one name is specified, 
then the Equal command directly compares the two directories. That is, the 
command 


Equal Dirl Dir2 
compares Dirl (and all subdirectories) with Dir2. 


Type — Built-in. 
Input None. 
Output Differences are written to standard output. 


Diagnostics _—_Errors are written to diagnostic output. 


Status The following status values may be returned: 


0 Identical files 

1 Syntax error 

2 Inaccessible or missing parameter 
3 Files not equal 
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Options 


Examples 


See also 


-i Ignore files missing from directory name; that is, if files in 
targetName are not present in mame, Equal won't report the 
missing files as differences. 


-d Compare the data forks only. 

-r Compare the resource forks only. 

-p “List progress information as files are compared. 

-q Remain quiet about differences; return status codes only. 


Equal Options 


[ignore missing files | 
; C] Progress Information | 
| Cl quiet made | 


Forks to eee 


@ Both forks 1 
© Data fork only | Output Error 


Command Line 
on 
Compare files and directories for equality. om Eane ar — 


Equal Filel FilelBackup 


© Resource fork only 


Reports if the files are different and at what point they differ, in a message such as 


Filel FileiBackup differ in data fork, at byte 5 


Equal -i HD:Dirl Disk1i:Dirl 


Compares all files and directories in HD:Dir1 with files and directories with the same 
names found in Disk1:Dir1, and reports any differences. This command does not 


‘report files in Disk1:Dir1 that aren’t found in HD:Dir1. 


Equal -i -d Backup: HD:Source 


Compares the data forks of all files on the volume Backup: with all those of the same 
name in the directory HD:Source. 


Equal -p Old:s.c HD:Source 


Compares all files on Old: ending in “.c” with their counterparts in HD:Source. 
Prints progress information as the comparison proceeds. 


Compare command. 
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Syntax 


Description 


Type 

Input 
Output 
Diagnostics 


Status . 


Options 


Examples 
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Erase—initialize volumes 


‘Erase [-y] (-s] volume... 


Initializes the specified volumes— the previous contents are destroyed. A volume 
name’ must end with a colon (:). If volume is a number without a colon, it’s 
interpreted as a disk drive number. . 


A dialog box requests confirmation before proceeding with the command, unless the 
-y option is specified. The -y option can be used in scripts to avoid this interaction. 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


The following status values may be returned: 


0 Successful initialization 

1 Syntax error . 

2 No such volume, or boot volume © 

3 Errors during the initialization procedure 


-y Answer “yes” to the confirmation dialog, causing initialization to 
begin immediately. 


-S Format the disk for single-sided use (that is, as a 400K, non-HFS 
disk). 


Erase Reports: 


Initializes the volume titled Reports. 


Erase 1 


Initializes the volume in drive 1 (the internal drive). The disk will be formatted as a _ 
400K: disk if drive 1 is a 400K drive, or as an 800K disk if drive 1 is an 800K drive. 


Syntax 


Description 


Evaluate—evaluate an expression 
Evaluate [ expression... ] 


The list of words is taken as an expression. After evaluation, the result is written to 
standard output. Missing or null parameters are taken as zero. You should quote string 
operands that contain blanks or any of the characters listed in the table below. 


The operators and precedence are mostly those of the C language; they’re described 
below. 


Expressions: An expression can include any of the following operators. dn some 
cases, two or three different symbols can be used for the same operation.) The 
operators are listed in order of precedence—within each group, operators have the | 
same precedence. 


Operator Operation 
1. (expr) Parentheses are used to group expressions 
a Unary negation 
~ Bitwise negation 
! NOT - __ Logical NOT 
eas Multiplication 
+ DIV Division 
% MOD Modulus division 
4.+ Addition 
= . Subtraction 
5. << Shift left 
>> Shift right 
6. < Less than 
<= s Less than or equal to 
> Greater than 
>= 2 Greater than or equal to 
Dek _ Equal 
I= <>  #  Notequal 
=~ Equal—regular expression 
1~ Not equal—regular expression 
8. & Bitwise AND 
9. A Bitwise XOR 
10. | . Bitwise OR 
11. && AND Logical AND 
12. II * OR Logical OR 


All operators group from left to right. Parentheses can be used to override the 
operator precedence. Null or missing operands are interpreted as zero. The result of 
an expression is always a string representing a decimal number. 


The logical operators !, NOT, 7, &&, AND, | |, and OR interpret null and zero 
operands as false, and nonzero operands as true. Relational operators return the 
value 1 when the relation is true, and the value 0 when the relation is false. 
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Type 
Input 


Output 


Diagnostics 


Status 


Options 


} 


The string operators ==, !=, =~, and !~ compare their operands as strings. All others 
operate on numbers. Numbers may be either decimal or hexadecimal integers 
representable by a 32-bit signed value. Hexadecimal numbers begin with either $ or 
Ox. Every expression is computed as a 32-bit signed value. Overflows are ignored. 


The pattern-matching operators =~ and !~ are like == and != except that the right- 


_ hand side is a regular expression which is matched against the left-hand operand. 


Regular expressions must be enclosed within the regular expression delimiters /.. J. 
Regular expressions are summarized in Appendix B. 


Note: There is one difference between using regular expressions after =~ and !~.and - 
using them in editing commands—when evaluating an expression that contains the 
tagging operator, ®, the Shell creates variables of the form {®7}, containing the 
matched substrings for each ® operator. (See the examples below.) 


Filename generation, conditional execution, pipe specifications, and input/output 
specifications are disabled within expressions, to allow the use of many special 
characters that would otherwise have to be quoted. 


Expressions are also used in the If, Else, Break, Continue, and Exit commands. 


Built-in. 


‘None. 


The result of the expression is written to standard output. Logical operators return the 
values 0 (false) and 1 (true). 


Note: To redirect Evaluate’s output (or diagnostic output), you'll need to enclose the 
Evaluate command in parentheses; otherwise, the > and 2 symbols will be 
interpreted as expression operators, and an error will occur. (See the third example 
below.) 


Errors are written to diagnostic output. 


The following status values may be returned: 


0 Valid expression — 
1 Invalid expression 


None. 
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Examples 


See also 


Evaluate (1+2) * (3+4) 
Does the computation and writes the result to standard output. 


Set lines ‘Evaluate {lines} + 1° 


The Set command increments the value of the Shell variable {lines}—the Evaluate 
command enclosed in command substitution characters C...~) is replaced by its 
output. 


( Evaluate "{aPathname}" =~ /(([—:]+:)*)®l=/ ) > Dev:Null 
Echo (@1} 


These commands examine a pathname contained in the variable {aPathname}, and 
return the directory prefix portion of the name. In this case, Evaluate is used for its 
side effect of enabling regular expression processing of a filename pattern. The right- 
hand side of the expression (/ ( ({[—:]+:) *) ®1=/) is a regular expression that 
matches everything in a pathname up to the last colon, and remembers it as the Shell 
variable {®1}. Evaluate’s actual output is not of interest, so it’s redirected to the bit 
bucket, Dev:Null. (See “Pseudo-Filenames” in Chapter 5.) Note that the use of I/O 
redirection means that the Evaluate command must be enclosed in parentheses so 
that the output redirection symbol, >, is not taken as an expression operator. 


This is a complex, but useful, example of implementing a “substring” function. For a 
similar example, see the Rename command. 


“Structured Commands” in Chapter 5. 
“Pattern Matching (Using Regular Expressions)” in Chapter 6, and Appendix B. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 


Execute—execute a script in the current scope 
Execute commandFile 


Executes the script as if its contents appeared in place of the Execute command. This 
means that variable definitions, exports, and aliases in the script will continue to exist 
after it has finished executing. (Normally these definitions, exports, and aliases would 
be local to the script.) Any parameters following script are ignored. Any parameters 
to the enclosing script are available within script. 


Note: If script is not a command file (that is, if it’s a built-in command, tool, or 
application), the command is mun as if the word Execute did not appear. Parameters 
are passed to the command as usual. 


Built-in. 

None. 

None. 

None. 

Execute returns the status returned by script. 
None. 


Execute "({ShellDirectory}"Startup 


Executes the Startup (and UserStartup) scripts. This command is useful for testing any 
changes you’ve made to the Startup-UserStartup script. Variable definitions, exports, 
and aliases set in Startup and UserStartup will be available after Startup is done 
executing. 


“Defining and Redefining Variables” in Chapter 5. 
“The Startup and UserStartup Files” in Chapter 5. 
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Exists—confirm the existence of a file or directory 
Syntax Exists [-d | -f | -wl[-q] name... 


Description Determines the existence of the file or directory name. The options help you to 
distinguish between directories and files and different access permissions. The non- 
existence of name is not considered an error (status remains zero). 


Type Built-in. 

Input None. 

Output Files that exist and match the specifications have their names written to standard 
output. 


Diagnostics — Errors are written to standard output. 


Status The following status codes may be returned: 


0 No error 
J Syntax error 
2 Other error 


Options -d Check if name is a directory. 
-f Check if name is a file (as opposed to a directory). 
-w Check if the user has write access to the file name. A file cannot be 


written to if it is open or locked. 


-q Do not quote pathnames that are written to standard output. 


Example If Not "“Exists -d HD:dir*" 
NewFolder HD:dir 
End 
Duplicate =.c HD:dir 


This example creates a new directory and copies all files ending with “.c” in current 
directory to this new directory. 


See also Newer command. 


Exists I-81 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 
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Exit 


Exit—exit from a script 
Exit [ status] [ If expression | 


If the expression is nonzero (that is, true), Exit terminates execution of the script in 
which it appears. When used interactively, Exit terminates execution of previously 
entered commands. Status is a number; if present, it is returned as the status value of 
the script. Otherwise, the status of the previous command is returned. If the “If 
expression” is omitted, the Exit is unconditional. (For a definition of expression, 
refer to the description of the Evaluate command.) 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


If status is present, it is returned as the status value of the script. If the expression is 
invalid, -5 is returned. Otherwise, the status of the last command executed is 
returned. 


None. 


Exit (ExitStatus} 


As the last line of a script, this Exit command would return as a status value whatever 
value had previously been assigned to {ExitStatus}. 


Evaluate command (for information on expressions). 
“Structured Commands” in Chapter 5. 
{Exit} and {Status} variables, in “Variables,” Chapter 5. 


Export—make variables available to programs 
Syntax Export [-r | -s | name... ] 


Description Make the specified variables available to scripts and tools. The list of variables 
exported within a script is local to that script. An enclosed script or tool inherits a 
list of exported variables from the enclosing script . (See Figure 5-1 in Chapter 5 for 
clarification.) 


Note: You can make a variable available to all scripts and tools by setting and 
exporting it in the Startup or UserStartup files. (Startup acts as the enclosing script for 
all Shell operations.) 


If no names are specified, a list of exported variables is written to standard output. 
(Note that the default output of Export is in the form of Export commands.) 


Type Built-in. 
Input None. 
Output If no names are given, Export writes a list of exported variables to standard output. 


Diagnostics None. 


Status Export may return the following status values: 


0 No errors 
1 Syntax error 


Options -r Reverse the sense of the output, causingExport to generate 
Unexport commands for all exported variables. 


-S Suppress the printing of “Export” before the exported variables. 


Example Set AIncludes "{(MPW}AIncludes:" 
Export AIncludes 


Defines the variable {AIncludes} as the pathname "(MPW}AIncludes:", and makes it 
available to scripts and programs. 


See also Unexport, Set, and Execute commands. 


“The Startup and UserStartup Files” in Chapter 5. 
“Exporting Variables” in Chapter 5. 
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Syntax 


Description 


Type 
Input 


Output 


Diagnostics 


Status 


Options 


Example 


Limitation 


FileDiv—divide a file into several smaller files 
FileDiv [-f] [-n splitpoint}] [-p] file [ prefix] 


FileDiv is the inverse of the Catenate command. It is used to break a large file into 
several smaller pieces. The input file is divided into smaller files, each containing an 
equal number of lines determined by the splitpoint (default=2000). The last file 
contains whatever is left over. | 


There is also an option Cf) for splitting a file only when a form feed character 
(ASCII $0C) occurs as the first character of a line that is beyond the splitpoint. This 
option lets you split a file at points that are known to be the tops of pages. 


Each group of splitpoint lines is written to a file with the name prefixNN, where NV is a 
number starting at 01. If the prefix is omitted, the input file name is used as the prefix. 


Tool. 
An input file must be specified in the command line. Standard input is not used. 


FileDiv creates files with names of the form prefAxNN, where NN is a number. (If 
prefix is omitted, the input filename is used as a prefix.) Standard output is not used.. 


Parameter errors and progress information are written to diagnostic output 


FileDiv may return the following status values: 


0 Normal termination 
1 Parameter or Option error 
Z Execution terminated 


-f Split the input file only when at least splitpoint lines have been 
written to the current output file and there is a form feed character 
CASCII $0C) as the first character of a line. The line containing the 
form. feed becomes the first line in the next output file. 


-n splitpoint Split the input file into groups of splitpoint lines Cor, if the -f option 
was specified, splitpoint or more lines). If the -n option is omitted, 
2000 is assumed. 


-p Write version information and progress information to diagnostic 
output. 


FileDiv -f -n 2500 Bigfile 


Splits Bigfile into files of at least 2500 lines; splits the file at points where there are 
form feed characters. The output files have the names BigfileNN, where NN is 01, 02, 
and so on. 


The maximum length of an input line is 255 characters. 
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Files—list files and directories 
Syntax Files [ option... ] { slugname...] 


Description For each disk or directory named, Files lists its contents; for each file named, Files 
writes its name and any other information requested. Information is written to 
standard output. When a directory is listed, all subdirectories are listed first in 
alphabetical order, followed by all files in alphabetical order. If no name is given, the 
current directory is listed. 


Type Built-in. 
Input None. 
Output File information is written to standard output. 


Diagnostics Errors and warnings are written to diagnostic output. 


Status Files may return the following status values: 


0 All names were processed successfully 
1 Syntax error 
2 An error occurred 


Options -c creator List only those files with the given file creator. 
-d List subdirectories only. 
-f Give full pathnames for all files listed. 
-i Treat directories on the command line as files (ignore differences). 


That is, don’t list the contents of directories, just list the directory 
and any other information requested. 


-m count Multi-column output. This option is not valid if specified with 
-lor -x. 
-n No header in the long or extended format. Without the -l or -x 


option, this option has no meaning. 


-q Don’t quote names in the output. Normally, the Files command 
quotes names that contain spaces or special characters. 


-r Recursively list subfolders encountered; that is, list every file in 
every directory. 


-S Suppress the printing of directory names. Useful when combined 
with the -r option to get listing of all files (excluding directories). 
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Examples 
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-t type List only those files with the given file type. 


-x format Extended format. This option generates a listing similar to that 
produced by the -I option, except that the fields to be printed are 
determined by format. Format is a string composed of the 
following letters (in any order) where the order determines the fields 
position in the output: 


Flag attributes 

Logical size in bytes of the data fork 

Creator of file ('Fldr' for folders) 

Creation date 

Group (applies only to folders on AppleShare) 
Physical size in kilobytes of both forks 
Modification date 

Owner (applies only to folders on AppleShare) 
Privileges (applies only to folders on AppleShare) 
Type of file 

Logical size in bytes of the resource fork 


"T9090 053 wm andnoe 


files -r -s -f 

HD: source:defs.h 
HD:source:main.c 

HD: source:backup:main.c 
HD: source:backup:defs.h 
HD:source: junk: tmpfile 


Recursively lists the contents of the current directory, giving full pathnames and 
suppressing the printing of directory names. 


files -d 
:backup: 
:junk: 


Lists only the directories in the current directory. 


Files -i -x kd "{AIncludes}" 
Name Size Creation-Date 


HD:MPW:AIncludes: 365K 8/25/87 5:32 AM 


Lists the size and creation date of the "{AIncludes}" directory. Notice how the -i option 
is used to avoid printing the contents of the directory. 


files -m 2 
:backup: deFs.h 
:junk: main.c 


This is the two-column format. Notice the order of the files. 


Find—find and select a text pattern 
Syntax Find [-c count] selection { window] 


Description Creates a selection in window. If no window is specified, the target window (the 
second window from the front) is assumed. It’s an error to specify a window that 
doesn’t exist. 


Selection is a selection as defined in Chapter 6 and in Appendix B. 


Note: Searches do not necessarily start at the beginning of a window—a forward 
search begins at the end of the current selection and continues to the end of the 
document. A backward search begins at the start of the current selection and 
continues to the beginning of the document. 


All searches are case insensitive by default. You can specify case-sensitive searches by 
first setting the Shell variable {CaseSensitive} to a nonzero value. (You can 
automatically set {CaseSensitive} by checking Case Sensitive in the dialog boxes 
displayed by the Find and Replace menu items.) 


Type Built-in. 
Input None. 
Output None. 


Diagnostics Errors are written to diagnostic output. 


Status The following status values may be returned: 


0 At least one instance of the selection was found 
1 Syntax error 
2 Any other error 


Option -¢c count For a count of 7, find the mth occurrence of the selection. 
Examples Find ° 
Positions the insertion point at the beginning of the target window. 


Find -c 5 /procedure/ Sample.p 
Selects the fifth occurrence of “procedure” in the window Sample.p. 


Find 332 
Selects line 332 in the target window. 


See also “Selections” and “Pattern Matching” in Chapter 6. 
“Find Menu” in Chapter 3. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 
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Font—set font characteristics 
Font fontname /fontsize { window ...] 


Change the font family and point size of all text in window to fontname and /fontsize. 
Both fontname and /fontsize are required. It’s an error to specify a window that 
doesn’t exist. If no windows are specified, the command operates on the target 
window (the second window from the front). 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


Font may return the following status values: 


0 Successful completion 
1 Error in parameters 
2 An illegal fontname or fontsize was specified 


None. 


Font Monaco 12 


Changes the font of the target window to Monaco 12 point 


For... —repeat commands once per parameter 


Syntax For name In word... 
commana... 
End 


Description Executes the list of commands once for each word from the “In word...” list. The 
current word is assigned to variable name, and you can therefore reference it in the 
list of commands by using the notation {mame}. You must end each line with either a 
return character (as shown above) or with a semicolon (;; ). 


The Break command can be used to terminate the loop. The Continue command can 
be used to terminate the current iteration of the loop. 


The pipe specification (1), conditional command terminators (&& and | |), and 
input/output specifications (<, >, >>, 2, and 22) may appear following the End, and 
apply to all of the commands in the list. . 


Type Built-in. 
Input None. 
Output None. 


Diagnostics Errors are written to diagnostic output. 


Status The following status values may be returned: 


QO The list of words or list of commands was empty 
-3 There was an error in the parameters to For 


Otherwise, the status of the last command executed is returned. 


Options None. 


FOP. I-89 


Examples For i In1 2 3 
Echo i = (i} 


End 
Returns the following: 


i=zal 
i=2 
i = 3 


For File In ».c 
C "{File}" ; Echo "{File}" compiled. 
End 


This example compiles every file in the current directory whose name ends with the 
suffix “.c”. The Shell first expands the filename pattern =.c, creating a list of the 
filenames after the “In” word. The enclosed commands are then executed once for 
each name in the list. Each time that the loop is executed, the variable {File} 
represents the current word in the list. {File} is quoted because a filename could 
contain spaces or other special characters. 


For file in Startup UserStartup Suspend Resume Quit 

Entab “(file}" > temp 

Rename -y temp "{file}" 

Print <n "{tile}™ 

Echo "({file}" 
End 
This example entabs (replaces multiple spaces with tabs) the five files listed, prints 
them with headings, and echoes the name of each file after printing is complete. You 
might want to use this set of commands before making copies of the files to give toa 
friend. Entabbing the files saves considerable disk space, and printing them gives you 
some quick documentation to go with the files. 


See also Loop, Break, and Continue commands. 
“Structured Commands” in Chapter 5. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


GetErrorText—display text for system error numbers 


GetErrorText [-f filename] [-s filename] [-n] [-p] errnbrl,insert,...] ... 
GetErrorText -i idnbr ... 


Displays the error messages corresponding to a set of specified error numbers or ID 
numbers. By default, GetErrorText assumes the error numbers correspond to 
Macintosh Operating System system error numbers. The file SysErrs.Err is a special 
file used by MPW tools to determine the error messages corresponding to system 
error numbers. Other system error message files may be specified by using the 

-S option. 

In addition to system errors, some tools have their own error message files. For 
example, in the case of the Assembler, it is in the data resource fork of Asm itself. For 
such tools, you can display the error messages corresponding to tool error numbers 
by specifying the -f option. In this case, you may specify sample inserts, along with 
the error numbers, for error messages that take inserts, as shown above. 


GetErrorText can also display the meanings of the ID numbers reported by the 
System Error Handler in alert dialog boxes. The -i option is used for this purpose. 


Tool. 


All input is specified through the parameters. 


The error messages are written to the standard output. 


Errors are written to the diagnostic file. 


GetErrorText may return the following status values: 


0 Normal termination 
1 Parameter or option error 
2 Execution terminated 
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A tool’s error message filename. Either -f or -s, but not both, may 
be specified. 


Report the meaning of the specified System Error Handler ID 
number. 


The error message file name for a system error. Either -f or -s, but 
not both, may be specified. The default is -s SysErrs.Err. 


Do not generate error numbers as part of the error messages. This 
option is ignored if system errors are displayed. 


Writes GetErrorText’s version information to the diagnostic file. 


GetErrorText ~43 -44 =-45 


Displays the error messages corresponding to system errors -43, -44, and —45. 


GetErrorText -i 28 2 


Displays the error messages corresponding to system ID numbers 28 and 2. 


Options -f filename 
-i fdnbr 
-s filename 
-n 
“p 
Examples 
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syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


GetFileName—display a standard file dialog box 


GetFileName [-t TYPE]... | -p | -d] [-q] [-m message] [-b buttontitle] [pathname] 


GetFileName displays a standard file dialog box. Either SFPutFile or SFGetFile is 
called, and the returned filename or pathname is written to standard output. The 
standard file starting directory is set to pathname if specified. If pathname 
includes a local filename and if SFPutFile is called, the local filename is used as 
the default filename. See the examples. 


Tool. 
None. 


The filename or pathname you select is written to standard output. The pathname 
is always a full pathname starting at the selected volume’s root. 


Parameter errors are written to diagnostic output. 


The following status values may be returned: 


0 User specified a file and no errors occurred 

1 Parameter or option error 

2 System error 

4 User canceled the standard file dialog box 

-p Display an SFPutFile dialog box. 

-d Display an SFGetFile dialog for selecting a directory. 
-m msg Specify a prompt message. 


-b buttontitle Specify the title for the default button in the various dialog boxes. 
If this option is not specified, Open is used in the standard SFGetFile 
dialog box, Save is used in the standard SFPutFile dialog box, and 
Directory is used in the directory SFGetFile dialog box. 


-q Suppress quoting the filename written to standard output. 


-t type Specify a type to use in filtering the SFGetFile. Up to four types may 
be specified. 
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Examples open ‘GetFileName -t TEXT ({pinterfaces}- 
Opens the text file in directory {pinterfaces} chosen in SFGetFile by the user. 


GetFileName -p HD:MPW:StartUp 


An SFPutFile dialog box is displayed with the directory set to HD:MPW: and StartUp is 
displayed in the textedit field of the dialog box. 


Limitation The resulting filename cannot be longer than 255 characters. 


See also “The Standard File Package,” Inside Macintosh, Volume I. 
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GetListitem—display items for selection in a dialog box 
Syntax GetListItem [ option... ][ items... ] 


Description Takes the items on the command line Cor, if no items are present on command | 
line, then from standard input) and lists them in a dialog box. Items in the list 
can be selected with the mouse and modifier keys. Selected items are written to 
standard output when the OK button is clicked. 


Type Tool. 
Input Reads standard input for the items if none are specified on the command line. 
Output Selected items are written to standard output if the OK button is clicked. 
Diagnostics Errors are written to diagnostic output. 
Status GetListltem may return the following status values: 

0 No errors 

1 Syntax error (bad option) 


2 Cancel button was clicked 


Options -d item Item is entered as an element in the list and comes up selected. 
This option may be specified more than once. 


-m message Display message above the list of items. 


-q Don’t quote items in the output. 
-r TOWS Make the list with this many rows. 
-w width Make the list this many pixels wide. 


Note: GetListItem uses the -r and -w values only as a guideline. For 
example, if the value given for rows is larger than the number of 
rows on the screen, GetListltem will use a smaller number of rows 
than requested. GetListItem does not give error messages when the 
-f Or -w arguments are out of range. Rather, it makes a reasonable 
guess at a value. 
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Examples print ‘files -t TEXT | GetListItem -m "Select files to print:'™ 


Lists all text files in the current directory and prints those selected by the user, as 
shown below. 


Select files to print: 


characters.h 
makefile 


select.c 
select.r 


Ce) Gan 


GetListItem red blue -d green -m "Pick your favorite color:" 


Display a list of three colors with green pre-selected, as shown below. 


Pick your favorite color: 


Limitation GetListItem cannot handle a list greater than 32K characters. 


I-96 GetListitem 


Syntax 


Description 


Help—display summary information 
Help [-f helpFile] [ command... | 


Help writes information about the specified commands to standard output. If no 
command is specified, information about Help is written to standard output 
Command can include any of the following: 


commandName Information about commandName 


commands A list of all MPW commands 

expressions A summary of expressions 

patterns A summary of pattern specifications @egular expressions) 
selections A summary of selection operators 

characters A summary of MPW Shell special characters 

shortcuts A summary of MPW shortcuts 


By default, the Help command looks for information in the file MPW.Help. It looks 
for this file first in {ShellDirectory}; if the file isn’t found, Help looks in 
{SystemFolder}. 


The following syntax notation is used to describe Macintosh Programmer’s Workshop 
commands: 


{ optional} Square brackets mean that the enclosed elements are optional. 

repeated... Ellipses indicate that the preceding item can be repeated one or more 
times. 

alb A vertical bar indicates an either/or choice. 


(grouping) Parentheses indicate grouping (useful with “!” and *...”). 


< input If input is not specified, the command reads from standard 
input. 
> output The command writes to standard output. 


2 progress Progress information is written to diagnostic output (with the 

-p option). 
A Help file is a set of entries, each separated by a blank line beginning with one 
hyphen. Each entry may contain one or more lines. The first word of the first line in 
each entry is the keyword that is looked up by the Help command. When the word is 
located, the line in which it occurs, and all following lines until a separator is 
encountered, are written to standard output. If no parameters are given to the Help 


command, then the first entry is written to standard output. Here is an excerpt from 
the MPW.Help file: 


New (name...] 


Newer [-c] [-e] [-q] file... target > newer 
-c # compare creation dates 
-e # report names that have the same (equal) 
# date as target 
-q # don't quote filenames with special characters 


NewFolder name... 
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Type 


Input 


Output 


Diagnostics 


Status 


Option 


Example 
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Built-in. 

None. 

Command information is written to standard output. 
Errors are written to diagnostic output. 


The following status values may be returned: 


0 Information was found for the given command 

1 Syntax error 

2 A command could not be found, or error in parameters 
3s The help file could not be opened 


-f helpFile Specify help file to be searched. (A help file is an ordinary MPW 
text file.) The default file is MPW.Help. 


Help Rez 
Writes information such as 


Rez [option...] [file..] < file 2 progress 

-a({ppend] # merge resource into output resource file 

-align word | longword # align resource to word or longword boundries 

-c(reator] creator # set output file creator 

-d{efine] name(=vdlue] # equivalent to: #define macro [value] 

-i{nclude] pathname # path to search when looking for #include files 

-o file # write output to file (default Rez.Out) 

-ov # ok to overwrite protected resources when 
appending 

-p write progress information to diagnostics 

-rd suppress warnings for redeclared types 

-ro set the mapReadOnly flag in output 


-~s({earch] pathname 
-tlype] type 
-u{ndef] name 


path to search when looking for INCLUDE resources 
set output file type 
equivalent to #undef name 


te te 4e 4b 4r fe 


If... —conditional command execution 


syntax If expression 
command... 
[ Else If expression 
command...)... 


Description Executes the list of commands following the first expression whose value is nonzero. 
(Null strings are considered zero.) At most one list of commands is executed. You 
may specify any number of “Else If” clauses. The final Else clause is optional. The 
return characters (as shown above) or semicolons must appear at the end of each 
line. 


The pipe specification (|), conditional command terminators (&& and | 1), and 
input/output specifications (<, >, >>, 2, and 22) may appear following the End, and 
apply to all of the commands in the list. 


For a definition of expression, see the description of the Evaluate command. 


Type Built-in. 
Input None. 
Output None. 


Diagnostics Errors are written to diagnostic output. 


Status 0 None of the lists of commands were executed 
-1 Invalid expression 


Otherwise, it returns the value returned by the last command executed. 


Options None. 
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Examples 


See also 
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If... 


If {Status} == 
Beep 1la,25,200 
Else 
Beep -3a,25,200 
End 


Produces an audible indication of the success or failure of the preceding command. 


For window in *Windows* 
If "(window)" != "(Worksheet}" AND "“({window}" != "{Active}" 
Close "{window}" 
End 
End 
Closes all of the open windows except the active window and the Worksheet window. 
(Refer also to the Windows command.) 


The following commands, as a script, would implement a trivial case of a general 
“compile” command: 


LE Ly Sef eC7 
C (COptions}) "{1}" 
Else If "{1}" =~ /s.p/ 
Pascal (POptions} "{1}" 
End 
If the above commands were saved in a file (say, as “Compile”), both C and Pascal 
programs could be compiled with the command 


Compile filename 


Evaluate command (for a description of expressions). 
“Structured Commands” in Chapter 5. 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Lib—combine object files into a library file 


Lib [option...] objectFile... 


Combines the specified object files into a single file. By convention, input files end 
in the suffix “.o”, which must be present. In addition, input files must have type 'OBJ ' 
and creator 'MPS '. 


Lib is used for the following: 


O 
O 


Combining object code from different languages into a single file. 


Combining several libraries into a single library, for use in building a particular 
application or desk accessory. This can greatly improve the performance of the 
Linker. 


Deleting unneeded modules (with the -dm option), changing segmentation (the 
-sg and -sn options), or changing the scope of a symbol from external to local 

(the -dn option). (These options are useful when you construct a specialized library 
for linking a particular program.) 


Object files that have been processed with Lib result in significantly faster links when 
compared with the “raw” object files produced by the Assembler or compilers. 


The output of Lib is logically equivalent to the concatenation of the input files, except 
for the optional renaming, resegmentation, and deletion operations, and the 
possibility of overriding an external name. The resolution of external names in Lib is 
identical to Link—in fact, the two programs share the same code for reading object 
files. Although multiple symbols are reduced to a single symbol, no combining of 
modules into larger modules is performed, and no cross-module references are 
resolved. This behavior guarantees that the Linker’s output will be the same size 
whether or not the output of Lib was used. 


See “Library Construction” in Chapter 10 for a detailed discussion of the behavior 
and use of Lib. 


Tool. 


Lib does not read standard input. 


Lib does not write to standard output. The combined library output is placed in the 
data fork of the output library file. The default output file is Lib,Out.o—you can 
specify another name with the -o option. The output file is given type 'OBJ ' and 
creator 'MPS '. 


Errors and warnings are written to diagnostic output. Progress information is also 
written to the diagnostic file if you specify the -p option. 


Lib may return the following status values: 


0 
Z 
3 


No problem 
Fatal error 
User interrupt 
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Options 
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Lib 


-bs mn 


-d 


-df deleteFile 


Do a big execution of Lib, that is, -bf and -bs 4 options. 


Allow a big number of files; that is, keep only one input file open at 
a time. If Lib fails with a “too many files open” message, use this 
option. 


Set the buffer size for input to m7 blocks (512 bytes each). If Lib fails 
with a “heap error” or “out of memory” message, try this option. 
Values for 1m must be between 2 and 64. (The default is 16.) 


Note: Numeric values can be specified as decimal constants, or as 
hex constants preceded by a “$”. 


Suppress warnings for duplicate symbol definitions (data and 
code). 


Delete the list of external modules found in deleteFile. DeleteFile is 
a text file generated by the Linker option -uf. See the Link command 
and “Library Construction” in Chapter 10 for information. 


-dm name (,name ...] 


“Delete Module”—delete the specified external modules from the 


output file. name may be either an external module or entry-point 


name. For each entry-point mame, the entire module containing 
the entry point is deleted, together with all other entry names in the 
module. The contents of the module and all entry points are 
removed from the output file. 


Note: References to names deleted in this way will persist as 
references “by name.” That is, if the references are from active 
code, they’ll need to be resolved by external modules or entry 
points in another file. 


The primary use of this operation is to make the library file smaller, 
so subsequent links are faster. You can use the Linker option -uf, 
which lists unreferenced (“dead”) modules or entry points, to 
generate a list of names that can be deleted in this way. 


-dn name [,name ...] 


-O name.o 


“Delete Name”—delete the list of external names from the output 
file, by reducing their scope to local. -dn is a “gentle” deletion, in 
that it affects only the list of external module or entry-point names. 
The contents of the module, other entry points, references, and so 
on will still be present in the output file. References to names 
“deleted” in this way will continue to refer to the same code, but 
with local scope. This is a useful operation when a global name 
conflict occurs between two pieces of code, one of which is library 
code from which you don’t need to call the name directly. 


Place the output in file name.o. (The default name is Lib.Out.o). 


Write progress and summary information to diagnostic output. 


Example 


See also 


-sg newSeg=oldSeg il, oldSeg2 )... 
Change segment names. All code in the old segments named 
oldSeg1,oldSeg2,... is placed in the segment named newSeg. 


-sn oldSeg= newSeg 
Change a segment name. All code in the segment named o/dSeg is 
placed in the segment named newSeg. 
Note: The -sn and -sg options behave exactly as in Link, except that 
-sn is limited to identifiers on both sides of the equal sign. The 
arbitrary string for a desk accessory name can be introduced only 
with Link, not with Lib. The major difference between -sn and -sg is 
that the order of the option parameters o/dSeg and newSeg is 
reversed. (This is done for consistency with Link.) 


-w Suppress warning messages. 


Lib {CLibraries}* -o (CLibraries}CLibrary.o 


Combines all of the library object files from the {CLibraries} directory into a single 
library named CLibrary.o. For applications that require most or all of the C library 
files, using the new CLibrary file will reduce link time. 


Link, DumpObj, and DumpCode commands. 


“Optimizing Your Links” and “Library Construction” in Chapter 10. 
Appendix F. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 


See also 
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Line 


Line—find a line number 
Line 71 


Line finds line 7 in the target window. Parameter 7 is usually an integer, but may be 
any selection expression. The target window becomes the active (frontmost) window. 


Line is a script containing these two commands: 


Find "{1}" "{target}" # Find line n in the target window 
Open "{target}" # Bring the target window to the top 
Script. 

None. 

None. 


Errors are written to diagnostic output 


Status values can be returned by either the Find or the Open commands that make up 
the Line script: 


0 No errors 

1 Syntax error 

2 No target window; parameter not a number, other error 
3 System error 


None. 


Line 123 


Finds line 123 in the target window and makes the target window the new active 
window. 


### Undefined symbol: length 
File "Count.c"; Line 75 


The File and Line commands above are part of an error message produced by the C 
Compiler. The Assembler and Pascal Compilers produce errors when using similar 
formats. You can execute such error messages to find the line that contains the error. 


The command File is defined as an alias for Target in the Startup file. Thus File opens 
the specified file as the target window. Line then selects the offending line in the 
window and brings the window to the front. Notice that the remainder of the error 
message is a comment. 


Find command. 


Syntax 


Description 


Type 


Input 


Output 


Link—link an application, tool, or resource 
Link [ option... ] objectFile... 


Links the specified object files into an application, tool, desk accessory, or driver. 
The input object files must have type 'OBJ ' and creator 'MPS ', and must end in the 
suffix “.o”. Linked segments from the input object files are placed in code resources 
in the resource fork of the output file. The default output file name is Link.Out—you 
can specify other names with the -o option. 


For detailed information about the Linker, and instructions for linking applications, 
MPW tools, and desk accessories, see Chapters 9 and 10. The first dialog box of Link’s 
Commando dialog is reprinted here for convenience. 


The Linker’s default action is to link an application, placing the output segments into 
'CODE' resources. When you link an application, all old 'CODE' resources are deleted 
before the new 'CODE' resources are written. By default, resources created by the 
Linker are given resource names that are the same as the corresponding segment 
names. You can change a resource (segment) name with the -sn or -sg options; you 
can create unnamed resources with the -rn option. 


The Linker executes in three phases: 


mw Input phase: The Linker reads all input files, finds all symbolic references and 
their corresponding definitions, and constructs a reference graph. Duplicate 
references are found and warnings are issued. 


uw Analysis phase: The Linker allocates and relocates code and data, detects missing 
references, and builds the jump table. If the -1 or -x option is given, the Linker 
produces a linker map or cross-reference listing. The Linker also eliminates unused 
code. 


Output phase: The Linker copies linked code segments into code resources in the 
resource fork of the output file. By default, these resources are given the same 
names as the corresponding segment names. (The cursor spins backward during 
this phase.) 


Tool. 
Link does not read standard input. 


By default, linked segments are placed in 'CODE' resources in the resource fork of the 
output file. The default output file name is Link.Out—you can specify other names with 
the -o option. If the output file already exists, the Linker adds or replaces code 
segments in the resource fork. If the output file doesn’t exist, it is created with file type 


and output file creator to other values. 


Note: If a Linker error or user interrupt causes the output file to be invalid, then the 
Linker sets the modification date on the file to “zero” Gan. 1, 1904, 12:00 a.m.). This 
guarantees that Make will recognize that the file needs to be relinked. 
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Diagnostics 
Status 
Options 
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If you specify the -I option, the Linker writes a location map to standard output. The 
map is produced in location ordering, that is, sorted by segNum, segOffset. The 
format is divided into several fields: 

name segName_ segNum, segOffset [ @/TOffset] [#] [E] (C] [ ftleNum, defOffset | 

See Chapter 10 for more information. 


Errors and warnings are written to diagnostic output. Progress information is also 
written to diagnostic output if the -p option is specified. 


The following status values may be returned: 


0 No problem 
2 Fatal error 
3 ‘User interrupt 


Note: Numeric values for options can be specified as decimal constants, or as hex 
constants preceded by the dollar sign character ($). 


-b Do a big link; that is, do both -bf and -bs 4 options. 

-bf Allow a big number of files; that is, keep only one input file open at 
a time. If a link fails with a “too many files open” message, use this 
option. 

-bs blocks Set the buffer size for the Linker to blocks blocks (512 bytes each). If 


a link fails with a “heap error” or “out of memory” message, try this 
option. Values for blocks must be between 2 and 64. (The default 


is 16.) 
-c creator Set the output file creator to creator. The default creator is '2????'. 
-d Suppress warnings for duplicate symbol definitions (for data and 
code). 
-da Convert segment names to desk accessory names on output. Desk 


accessory names begin with a leading null character ($00). This 
option is used when linking assembly-language code into a final 
desk accessory (resource type 'DRVR'). 


-1 Write a location-ordered map to standard output. Usually, this 
option will be used with output redirection in effect. For example, 


Link ObjFile -l > MyMapFile 


-la List anonymous symbols in the location map (with the -1 option). 
The default is to omit anonymous symbols from the map. 


-lf In the location map data Cl option), include the location where 
symbols are defined in the input file, that is, the file number and 
byte offset of the module or entry-point record. (These records are 
discussed in detail in Appendix F.) The default is to omit the 
symbol definition location. 


-m mainEntry Set (or override) the main entry point specified in the object files. 


MainEntry is a module or entry-point name. 


Note: For an application or MPW tool, the main entry point is 
assigned the first jump-table entry, as required by the Segment 
Loader. If a main entry point is specified for a desk accessory, 
driver, or other type of link, for purposes of using the Linker’s 
active-code analysis feature, then the main entry point should be 
the first byte of code in the first Linker input file. (A desk accessory 
has no jump table.) 


-ma name =alias 


-O outputFile 


-opt 


“Pp 


-ra [segl=nn 


“rn 


“Module alias”—give the module or entry-point name the new 
name alias. This option lets you resolve undefined external 
symbols at link time, when the problem is caused by differences in 
spelling or capitalization. Note that you can’t use an alias 
specification to override an existing module or entry point. 


Place the Linker output in outputFile. If no -o option is specified, the 
default output filename is Link.Out The -o option uses the file in the 
system folder (or next level) if: 

1. the output file is not a full pathname, and 

2. it is not in the prefix folder, and 

3. it does not exist in the system folder or the volume root level. 
For more information on the Macintosh search path conventions 
see Inside Macintosh, Volume IV. 


Optimizes object Pascal. This option eliminates the need for the 
Optimize tool distributed with MacApp. 


Write progress and summary information to diagnostic output. 


Set the resource attributes of a segment or segments. If seg is 
specified, the single segment named seg is given the attribute value 
nn. If seg is omitted, then all segments except 0 and 1 are given the 
attribute value mm. CIf you intend to set the attributes of all segments, 
then you must specify this option before any other options that 
name segments, such as -sm and -sg.) The segment containing the 
main entry point (the 'CODE' resource with ID=1) must be set 
individually to override the default resource attributes (described in 
Chapter 8). 


Suppress the setting of resource names. (The default is to name each 
resource with the name of the segment.) Desk accessories must 
always be named. 
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-tt type=ID 


Set the output resource type to typeand the ID to JD. This option 
indicates the link of a desk accessory or driver—that is, only one 
resource is modified. (The default is type 'CODE' and resource IDs 
numbered from 0.) 


Assembly-language note: When you link a desk accessory or driver, 
the Linker uses PC-relative offsets, and attempts to edit JSR, JMP, 
LEA, or PEA instructions from A5-relative to PC-relative addressing 
mode. Other instructions will generate an error message. 


-sg newSeg=oldSeg Il, oldSeg2 ]... 


Change segment names. All code in the segments named o/dSeg1, 
oldSeg2,... is placed in the segment named newSeg. If no oldSeg 
(and no =) is specified, the Linker will map all code to newSeg. 


-sn oldSeg=newString 


“SS size 


-t type 


-uf deleteFile 


“Ww 
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Change a segment name. All code in the segment named o/dSeg is 
placed in the segment named newsString. 


There are two major differences between -sn and -sg: 


OQ -sn allows an arbitrary string for the new name, whereas -sg is 
intended only for identifiers separated by commas. 


GO The order of the oldSeg and newSeg parameters is reversed. 
For example, 
Link... @ 


-sg Main=SAConsol,StdIO,%ASInit @ 
-sn Main="MyDA" @ 


The first option combines the three specified segments into one 
segment named Main; the second option renames Main to 
“MyDA” : 


Change the maximum segment size to size. The default value is 
32760 (32K less a few overhead bytes). The value size can be any 
value greater than 32760. 


64K ROM note: Caution! Applications with segments greater than 
32K in size may not load correctly on Macintoshes with 64K ROMs. 


Set the output file type to type. The default type is APPL. 


List unreferenced modules in the text file deleteFile. (This option is 
useful in identifying dead source code.) This file can be used as 
input to Lib in building a specialized library that optimizes 
subsequent links. See the Lib command’s -df option and “Library 
Construction” in Chapter 10 for more details. 


Suppress warning messages. 


Note: Warnings generally indicate potential errors at run time. 


Examples 


See also 


-x crossRefFile Generate a cross-reference listing of active modules and entry 
points. The listing is ordered by module within each segment For 
each module, the following information is listed: each active entry 
point in the module; other modules and entry points that are 
referenced by the module; and other modules that reference this 
module. For each entry point in a module, the modules that 
reference the entry point are listed. 


Link Options 


Link output file Object Files... 
Link.out Type = | APPL CO Big Link 

- Creator [7777 | Single open file 
Segment attributes C2 Singie op 


CMake DA 1/0 Block size(EEa| 


(J Remove RSRC name: 


Rsrctype { __—_—i|-- (Listing options... 


Main entry point 


Command Line 
[ | 
Help ; Cancel 
Link creates executable code segments from one or more object modules 
| Link 


Link Sample.p.o @ 


"(PLibraries})"PInterface.o ad 
"(PLibraries}"PasLib.o @ 
"{Libraries}"Runtime.o ad 

-o Sample @d 

-l1 -la >Sample.map 


Links the main program file Sample.p.o with the libraries PInterface.o, PasLib.o, and 
Runtime.o, placing the output in Sample, and placing the Linker map in the file 


Sample.map. Sample will be an application, which can be launched from the Finder 
or executed from MPW. 


Link -rt MROM=8 -c 'MPS ' -t ZROM -ss 140000 @ 
-l > ROMLocListing <-o MyROMImage ({LinkList} 


Links the files defined in the Shell variable {LinkList} into a ROM image file, placing 
the output in the file MyROMImage. The segment size is set to 140,000 bytes, and the 
ROM is created as a resource 'MROM! with ID=8. The file is typed as being created by 
MPW (creator 'MPS '), with file type ZROM. The Linker location-ordered listing is 
placed in the file ROMLocListing. 


For additional examples, see “Linking” in Chapter 10 and the makefiles in the 
Examples folders for the languages you are using. 


Lib command and Appendix F, “Object File Format.” 
“Linking” and “More About Linking” in Chapters 9 and 10. 
The Segment Loader and the Resource Manager chapters in Inside Macintosh. 


Inside Macintosh, Volume IV, for information on the 128K ROM, System Folder, 
and Finder. 


LINK ll- 109 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 


Loop...End—repeat command list until Break 


Loop 
commana... 
End 


Executes the enclosed commands repeatedly. The Break command is used to 
terminate the loop. The Continue command can be used to terminate the current 
iteration of the loop. Return characters must appear as shown above, or be replaced 
with semicolons (;). 


The pipe specification (1), conditional command terminators (&& and | |), and 
input/output specifications (<, >, >>, 2, and 22) may appear following the End, and 
apply to all of the commands in the list. 


Built-in. 

None. 

None. 

None. 

Loop returns the status of the last command executed. 
None. 


The command file below runs a command several times, once for each parameter. 


### Repeat - Repeat a command for several parameters ### 
# Syntax: 


# Repeat command parameter... 
# 
# Execute command once for each parameter in the parameter 
# list. Options can be specified by including them with 
# the command name in quotes. 
# 
Set cmd "({1}" 
Loop 
Shift 
Break If "({1}" == "" 
{cmd} "{1}" 
End 


Notice that Shift is used to step through the parameters, and that Break ends the loop 
when all the parameters have been used. 


Break, For, and Continue commands. 


“Structured Commands” in Chapter 5. 
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Syntax 


Description 


Type. 


Input 


Output 


Diagnostics 


Status 


Make—build up-to-date version of a program 


Make [ option... ] [ targetFile... | 


Generates a set of Shell commands that you can execute to build up-to-date versions 


of the specified target files. (fF no target is specified then the first target on the left side 
of a dependency rule in the makefile will be built) Make allows you to rebuild only 
those components of a program that require rebuilding. Make determines which 
components need rebuilding by reading a makefile—this is a text file that describes 
dependencies between the components of a program, and the Shell commands 
needed to rebuild each component. You can specify makefiles with the -f option. 
After processing the makefiles, Make writes to standard output the appropriate set(s) 
of commands needed to rebuild the target(s). 


See “Using Make” in Chapter 10 for a description of the format of a makefile. The first 
dialog box of Make’s Commando dialog is reproduced here for convenience. 


Make executes in two phases: 


Q In the first phase, Make reads the makefile(s) and creates a file (target) dependency ~ 
graph. (The “beachball” cursor spins counterclockwise during this phase.) 


Q In the second phase, Make generates the build commands for the target to be built 
(the cursor spins clockwise)—if a target file doesn’t exist or if it depends on files 
that are out-of-date or newer than the target, Make writes out the appropriate 

- command lines for updating the target file. This process is recursive and “bottom 
up” so that commands for lower-level dependencies that need to be rebuilt are 
issued first. 


You can execute the generated build commands after Make is done executing. 
Tool. 


Standard input is not read. If you don’t specify a makefile with the -f option, Make tries 
to open a file called MakeFile. If no target file is specified on the command line, Make 


uses the first target encountered in the makefile. 


If any files need to be updated, Make writes the appropriate Shell commands to 
standard output. 


Errors, warnings, and diagnostic information Gf requested) are written to diagnostic 
output. If you specify the -p option, progress and sony information is also written 
to diagnostic output. 


The following status values may be returned: 
0 Successful completion 


7 Parameter or option error 


2 Execution error 
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Options - -d namel=value] Define a variable name with the given value. Variables defined 


-£ makefile 


“Pp 


-r [target] 


-S 
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from the command line take precedence over definitions of the 
same variable in the makefile. Thus definitions in the makefiles act 
as defaults that may be overridden from the command line. 


C] Make everything 

C Display progress information 
CJ Dispiay verbose output 

(] Display unreachable targets 


O Show structure 
O Find roots 


O Touch dates (C0 Ignore warnings 
Make Targets) 
Redirection... 


Command Line 
[ra : : | 
Make program (target) up-to-date by rebuilding everything that is 
apiao: [ Meke _| 


Rebuild everything that is a part of the specified or default target, 
regardless of whether targets are out of date. This option causes 
Make to output unconditionally all of the commands to rebuild the 
specified targets. 


Note: This option causes all components of the specified target to 
be rebuilt. However, it does not necessarily rebuild all targets if 


there are more than one top-level targets (roots) in the makefile. 


Read dependency information from makefile. You can specify 
more than one -f option—all dependency information is treated as 
if it were in a single file. (If no -f option is specified, the default file is 
a file named MakeFile in the current directory.) 


Write progress information to diagnostic output. (Normally, Make 
runs silently, unless errors are detected.) 


If no target is specified, the -r option will find all the roots (that is, 
the top level targets) of the dependency graph. (See the -s option.) 
If a target is specified, -r will find the root (or roots) for which it is a 
prerequisite. 


Note: This option overrides normal Make output. 


Show structure of target dependencies. This option writes a 
dependency graph for the specified targets to standard output, 
using indentation to indicate levels in the dependency tree. 
Circular dependencies are noted, if present. 


Note: This option overrides the normal Make output. It’s useful in 
debugging or verifying complicated makefiles. 


Example 


See also 


-t “Touch” dates of targets and their prerequisites, that is, bring files 
up to date by adjusting their modification dates, without outputting 
build commands. This option is used to bring a set of files up to date 
when they appear not to be, such as when you’ve only made 
changes to comments. The -t option does the minimal adjustment 
needed to satisfy the dependency relationships—files are touched 
only if required, and are given the date of their newest dependency, 
to minimize the repercussions of the date adjustments. This 
minimal adjustment of dates is especially useful if the touched file is 
also a prerequisite for other programs. 


Note: This option overrides normal Make output 


-u Write a list of unreachable targets to diagnostic output (for 
debugging). Unreachable targets are those mentioned in the 
makefile that are not prerequisites (or prerequisites of prerequisites) 
of the specified target to be rebuilt. 


-V Write verbose output to the diagnostic output file. This option is 
useful if you want to figure out what Make is doing and why. The 
diagnostic output will indicate if targets do not exist, whether or not 
they need to be rebuilt, and why they need to be rebuilt. It also | 
indicates targets in the makefile that were not reached in the build. 


-w Suppress warning messages. Warning messages are issued for things 
such as files with dates in the future and circular dependency 
relationships. 


Make -p -f MakeFile Sample 
_ Makes the target file Sample, printing progress information. Sample’s dependency 


relations are described in the makefile :AExamples:MakeFile: . 


Sample ff Sample.r 
Rez Sample.r -o Sample -a 
SetFile -a B Sample -c ASMP -t APPL #set bundle bit 


Sample gy: Sample.r Sample.a.o 
Link Sample.a.o -o Sample 


Sample.a.o f Sample.a 

Asm Sample.a 
The f (Option-F) character means “is a function of’—that is, the file on the left side 
depends on the files on the right side. If the files on the right side are newer, the 
subsequent Shell commands are written to standard output. (See Chapter 10 for 
details.) 


“Using Make” in Chapter 10, for the format of a makefile, examples, and other 
information about using Make. 


Makefiles for building sample programs are contained in the Examples folders: 
O :AExamples:Makefile 


OQ :PExamples:Makefile 


Q :CExamples:Makefile 
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Syntax 


Description 


Type 


— Input 


Output 


Diagnostics 


Status 


Options 


Example 


MakeErrorFile—create error message textifile 
MakeErrorFile [ option... ] [ file... ] 


MakeErrorFile creates error message files that are used to retrieve the error messages 
associated with error numbers. The ErrMgr unit in the ToolLibs.o library is used by 
programs to access the error files created by MakeErrorFile. SysErrs.Err is one such 
error file, used by various MPW tools to get the textual messages associated with 
Macintosh system error codes. See the documentation on the ErrMgr unit for more 
information on how error files are accessed. | 


Tool. 


Standard input is processed if no filenames are specified. Otherwise each file in the 
MakeErrorFile invocation is processed separately, with an error file created for each 
input. MakeErrorFile input files follow a very simple format, consisting of lines 
associating error messages with error numbers. Each line begins with an error 
number (in the range of 2-byte signed integers), followed by a space, followed by the 
corresponding error message text on the same line. 


If the -I listing option is specified, an ordered list of error numbers and messages will 
be written to standard output. The error file output is usually written to a file with the 
same name as the input file but. with a ".Err" extension (unless the -o option was used 
to specify the output name). If no input file was specified, then by default the input 
comes from standard input and the default error output file name is “Out.Err’”. 


Errors and warnings are written to diagnostic output. 


The following status values may be returned: 


— 0 No errors 


1 Syntax error 
2 Error in processing 


-l Write an ordered list of error numbers and messages to standard 
output. 
-0 objname Pathname for the generated error file if objname is a full pathname. 
If objname is a directory, it specifies where to put the error output 
file. 
-p Write progress information to diagnostic output. 


MakeErrorFile SysErrs -l >SysErrsList 


Writes an ordered list of system error numbers and messages to the file SysErrsList. 
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Syntax 


Description 


Type 

Input 
Output 
Diagnostics 


Status 


Options 


Mark—assign a marker to a selection 
Mark [-y | -2] selection name [window ] 


Mark assigns the marker name to the range of text specified by the selection in . 
window. If no window is specified the command operates on the target window 
(the second window from the front). The new marker name is included in the 
Mark menu when window is the current active window. A marker is associated to a 
logical, as opposed to absolute, range of text. The ranges of markers may 
overlap, but each marker must have a unique name. Marker names are case 
sensitive. 


A dialog box requests confirmation if the marker name conflicts with an existing 
marker name. The -y or -n option can be used in scripts to avoid this interaction. 


Deletion and insertion operations affect markers according to these rules: 


O Any editing outside the range of a marker will not affect the logical range of the 
marker, where “outside” means that the range of editing changes does not 
intersect the range of the marker. 


QO Any editing inside the range of a marker will change the logical range of the 
marker by the amount of the editing change. For example, adding 10 
characters to the inside of a marker’s range will increase the range of the 
marker by 10 characters. Another way to say this is: A marker has 
responsibility for all the characters added to (or deleted from) its range. 


O Any deletion that totally encloses a marker will delete the marker. 
Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


The following status values may be returned: - 


0 No errors 

Al Syntax error 

2 Error in processing 
3 System error — 


-yY Answer “yes” to any confirmation dialog that occurs, causing the 
old marker to be replaced with the new marker. 


-n Answer “no” to any confirmation dialog that occurs, so that the old 
marker is left intact. 
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. Example Mark § ‘Procedure 1' 


Assigns a marker with the name “Procedure 1” to the current selection in the target 


window. 
~ Limitation It is currently not possible to “Undo” the effects of any editing operations on markers. 
See also Unmark and Markers commands. 


“Mark Menu” in Chapter 3. 
“Markers” in Chapter 6. 
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syntax 


Description 


Type 

- Input 
Output 
Diagnostics 


Status 


Options 


Example 


See also 


Markers—list markers 
Markers [ -q ] [window ] 


Markers prints the names of all markers associated with window. The names are 
written one per line, and are ordered from the beginning to the end of the window. 


Tool. 
None. 


The list of marker names is written to standard output. 


Errors are written to diagnostic output 


- The following status values may be returned: 


0 No errors 

1 Syntax error 

2 Error in processing 
3 System error 


-q Do not quote marker names that contain special characters. (The default is to 
quote names with spaces or other special characters.) 


Markers "(Target}" 


Lists all markers associated with the target window. 


“Mark Menu” in Chapter 3. 
“Markers” in Chapter 6. 
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Syntax 


Description 


Type 


Input | 


Output 


Diagnostics 


’ Status 


Options 


_MDSCvi—convert MDS Assembler source 


MDSCvt [ option ...] { file ...] 


Converts the specified Macintosh MC68000 Development System (MDS) Assembler 
source files to the syntax required by the MPW Assembler. The following elements are 
converted: 


O tokens within statements 
O special tokens within macros 
O directives 


For a description of these conversions, refer to “MDS Conversion” in Appendix E of 


the MPW Assembler 2.0 Reference. 


Tool. 


Standard input is converted if no filenames are specified. If the -main, -g, or -! 
option is used, only one filename should be specified. 


If input is from the standard input file, the converted output is written to standard 
output. If the input file name is Name, the converted output is written to Name.a. 
The -n, -prefix, and -suffix options let you modify the naming conventions for the 
output file. | 


Parameter errors and progress information are written to diagnostic output. 


The following status values may be returned: 


0 Normal termination 
1 Parameter or option error 
2 Execution aborted 


-d Detab the input. All tabs are removed and replaced with spaces. 
The default setting is 8 spaces; this value can be changed with 
the -t option. 

' -e Detab the input dike the -d option), and entab the output as a 


function of the tab setting (either 8, or the value specified with the 
-t option). 


-f directivesFile Set the case (upper/lower) of directives according to the entries in 
directivesFile. The file MDSCvt.Directives is supplied for this 
purpose; you can edit it to change the capitalization. If you don’t 

F use this option, then all directives are converted to uppercase. 
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Example 


-g globals 


-main 


-n 


“P 


-pre(fix] string 


-suf [fix] string 


-t tabSetting 


-! identifier 


Convert a main program source and reserve globals space below 
A5. Globals may be specified in decimal or hexadecimal (by 
preceding the value with a $). The value specified must be negative. 
For example, 

~g -512 

-g $200 


Convert include files. No PROC or MAIN or END will be generated 
by MDSCvt. 


Do not insert MDS-compatible mode-setting directives (BLANKS 
ON and STRING ASIS) into the converted source. 


Convert a main program source. The conversion is done to make 
the file look like the main code and data modules. Only one file 
should be converted when using this option. 


Do not add the “.a” extension to the input filename to produce the 
output filename. Cf you use this option, you must also specify 
either -prefix or -suffix.) 


Write MDSCvt's version information and conversion status to 
diagnostic output. 


If the input filename is “Name”, the output filename is produced by 


prefixing the string to Name, that is, “stringName.a”. (You can 


suppress the “.a” suffix by using the -n option, or change it by using 
the -suffix option.) 


If the input filename is “Name”, the output filename is produced by 
appending the string to the filename, that is, “Namestring’. The 
default suffix is *.a”. 


Set the tab value for input and output files to tabSetting value (2 to 
255). The default setting is assumed to be 8. 


"When MDSCvt detects a name in the opcode field that is the same as 


an MPW directive, it appends the character c to make the name 
unique. (The default character is #.) 


Convert a main program source and define the main program’s 
entry point by the specified identifier. This option corresponds to 
the MDS Linker’s ! command. 


MDSCvt -t 8 MDSFilel.Asm MDSFile2.Asm 


Convert MDS Assembler source files MDSFilel.Asm and MDSFile2.Asm to MPW 
Assembler source files MDSFilel1.Asm.a and MDSFile2.Asm.a. The -t option sets the 
tab setting for both files to 8, and entabs the output files based on that value. It is 
assumed that neither file is a main program because the -main option has not been 
specified. If either file is a main program, then the -main option should be specified 
and only that file should be specified as input to MDSCvt. 
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Limitations See Appendix E in the MPW Assembler 2.0 Reference for details of conversions that 
. can and cannot be done with MDSCvt. 


See also — Appendix E, “MDS Conversion,” in the MPW Assembler 2.0 Reference. 


Il-120 - MOSCvt 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 


Mount—mount volumes 
Mount @rive... 


Mounts the disks in the specified drives, making them accessible to the file system. 
Drive is the drive number. 


Mounting is normally automatic when a disk is inserted. The Mount command is 
needed for mounting multiple hard disks, which cannot be “inserted,” or if a volume 
has been unmounted via the Unmount command. 


Built-in. 

None. 

None. 

Errors are written 6 diagnostic output. 


The following status values may be returned: 


0 The disk was mounted 
1 Syntax error 
2 An error occurred 


None. 


Mount 1 


Mounts the disk in drive 1 (the internal drive). 


Unmount and Volumes commands. 
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Syntax 


Description 


Move—move files and directories 
Move [-y | -n |--c] [-p] ‘name... targetName 


Moves name to targetName. (Name and targetName are file or directory names.) If 
targetName is a directory, then one or more objects (files and/or directories) are 
moved into that directory. If targetName is a file or doesn’t exist, then file or 
directory name replaces targetName. In either case, the old objects are deleted. 


Moved objects retain their current creation and modification dates. 


Type 
Input 
Output 


Diagnostics 


Status 


Options - 
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If a directory is moved, then its contents, including all subdirectories, are also 
moved. No directory moved can be a parent of targetName. 


A dialog box requests a confirmation if the move would overwrite an existing file or 
folder. The -y, -nm, or -c option can be used to avoid this interaction. 


Built-in. 
None. 
None. 


Errors are written to diagnostic output. Progress and summary information is also 
written to diagnostic output if the -p option is specified. 


Move may return the following status values: 


0 All objects were moved 

1. Syntax error 

2 An error occurred during the move 

4 Cancel was selected or implied with the -c option 


-y Answer “yes” to any confirmation dialog that may occur, causing 
conflicting files or folders to be overwritten. 


-n Answer “no” to any confirmation dialog that may occur, skipping 
the move for files or folders that already exist. 


-C Answer “cancel” to any confirmation dialog that may appear, 
causing the move to stop when a name conflict is encountered. 


-p List progress information as the move takes place. 


Examples Move Startup Suspend Resume Quit "(SystemFolder)" 


Moves the four files from the current directory to the System Folder. 


Move File :: 
Moves File from the current directory to the enclosing (parent) directory. 


Move -y Filel File2 


Moves File1 to File2, overwriting File2 if it exists. (This is the same as renaming the 
file.) 


See also Duplicate and Rename commands. 


“File and Window Names” in Chapter 4. 


“Filename Generation” in Chapter 5. 
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Syntax 


Description 


Type 

Input 
Output 
Diagnostics 


Status 


Options 


Examples 


See also 


MoveWindow—move window to h,v location 


' MoveWindow hv [window | 


Moves the upper-left corner of the specified window to the location (h,v) where h 
and v are horizontal and vertical integers. (Use a blank line to separate the numbers h 
and v on the command line.) The coordinates (0,0) are located at the left side of the 
screen at the bottom of the menu bar. If the location specified would place the 
window’s title bar entirely off the visible screen, an error is returned. If no window is 
specified, the target window (the second window from the front) is assumed. 


Built-in. 

None. 

None. 

Errors are written to diagnostic outpulL 


MoveWindow may return the following status values: 


0 No errors . 

1 Syntax error (error in parameters) 
2 The specified window does not exist 
> The h v location specified is invalid 


None. 


w 


MoveWindow 72 72 


Moves the target window’s upper-left corner to a point approximately one inch in 
from the upper-left corner of the screen, and one inch below the bottom of the menu 
bar. (There are about 72 pixels per inch on the Macintosh display.) 


MoveWindow 0 0 "“(Worksheet}" 


Moves the Worksheet window to the upper-left corner of the screen (below the menu — 
bar). 


SizeWindow, ZoomWindow, StackWindows, and TileWindows commands. 


I-124 ‘MoveWindow 


Syntax 


Description 


_Type 

Input 
Output 
Dignosties 


Status 


Options 


Examples 


See also 


New—open anew window 
New [ name... ] 


Opens a new window as the active (frontmost) window. If name is not specified, the 
Shell generates a unique name for the new window, of the form “Untited-n’, where n 
is a decimal number. If name already exists, an error results. 


You can use New to open several new windows by specifying a list of names separated 
by spaces. Note that New differs from Open —n by returning an error if the file already 
exists, whereas Open -n either opens an existing file or creates a new file. 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


New may return the following status values: 


0 No errors 

1 Syntax error (error in parameters) 

Z Unable to complete operation; a file with the specified name already exists 
3 System error 7 


None. 


New 


Opens a new window with a Shell-generated name. 


New Test.a Test.p Test.c 


Creates three windows called Test.a, Test.p, and Test.c. 


Open command. 
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Syntax 


Description 


Type 
Input 


- Output 


Diagnostics 


Status 


Options 
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- 


Newer—compare modification dates between files 


Newer [-e] [-cl [-q] mame... target 


Compares the modification dates of name and target. Files that have a more recent 
modification date than target have their names written to standard output. If the target 
is a non-existent file or directory then all names that exist are considered newer than 
the target. 


Built-in. 
None. 


Newer files are written to standard output. The names are written out one per line as 
they appear on the command line. 


Errors are written to diagnostic output. 


The following status values may be returned: 


0 - No error 
1 Syntax error 
2 ‘File not found 


-C Compare creation dates instead of modification dates or for 
creation dates when used with the -c option. 


-e Look for files with equal modification dates (or creation dates when 
used with the c option. 


-q Do not quote pathnames that are written to standard output 


Examples 


See also 


Newer main.c main.c.bak 


Writes out main.c if its modification date is more recent than its backup. 


Newer HD:Source:s.c HD:TimeStamp 


Writes to the screen all the source files in the Source directory that have been 
modified since the modification date of TimeStamp. 


If ‘Newer main.c main.c.bak* 
Duplicate main.c main.c.bak 
End 


Makes a backup copy of main.c only if it has been modified since the last backup was 
made. 


If "*Newer File.c File.h File.c.o'" 
C File.c -o file.c.o 
End 


Rebuilds the source file file.c if either file.c or file.h has been modified since file.c.o 
was last built. 


Exists command. 
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Syntax 


Description 


Type 

input 
Output 
Diagnostics 


Status 


Options 


Examples 


NewFolder—create a directory 
NewFolder name... 


Creates new directories with the names specified. Any parent directories included in 
the mame specification must already exist. 


Note: This command can be used only on hierarchical file system CHFS) disks. 
Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


The following status values may be returned: 


0 Folders were created for each name listed 

1 Syntax error 

2 An error occurred 

3 Attempt to use NewFolder on non-HFS volume 


None. 


NewFolder Memos 


Creates Memos as a subdirectory of the current directory. 


NewFolder Parent :Parent:Kid 


Creates Parent as a subdirectory of the current directory, and Kid as a subdirectory of 
Parent. 
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Open—open a window 
Syntax Open [-n | -r][-t] [ name... ] 


Description Opens a file as the active (frontmost) window. If neither name nor the -n option is 
specifed then StdFile’s GetFile routine is called, allowing the user to use a dialog box 
to choose a file. If name is already open as a window, that window becomes the active 
(frontmost) window. 


Type Built-in. 
Input None. 
Output None. 


Diagnostics Errors are written to diagnostic output. 


Status Open may return the following status values: 


0 No errors 

i Error in parameters 

Z Unable to complete operation; specified file not found 
3 System error 


Options -n Open a new window with the tide name. If name is not 
specified, a unique name is generated for the new window. If file 
name already exists, that file is opened. 


-r Open a read-only window associated with the file name. If file name 
doesn’t exist, an error occurs. 


-t Open the window as the target window rather than as the active 


window (that is, make it the second window from the front). This 
option is identical to the Target command. 


Examples Open 
Displays StdFile from which to choose a file to open. 


Open -r -t Test.a 


Opens the file Test.a as the target window, read-only. 


Cpen =.a 


Opens all of the files that end with “*.a”. 


See also Target, New, and Close commands. 
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Parameters—write parameters 
Syntax Parameters [ parameters ... ] 


Description The Parameters command writes its parameters, including its name, to standard 
output. The parameters are written one per line, and each is preceded by its 
parameter number (in braces) and a blank. This command is useful for checking the 
results of variable substitution, command substitution, quoting, blank interpretation, 
and filename generation. 


Type Built-in. 
Input None. 
Output Parameters are written to standard output. 


Diagnostics None. 


Status A status value of 0 is always returned. 
Options None. 
Example Parameters One Two "and Three" 


Writes the following three lines to standard output: 


{0} Parameters 
{1} One 
{2} Two 
{3} and Three 


Recall that "..." and '...' quotes are removed before parameters are passed to 
commands. 


see also Echo and Quote commands. 
“Parameters to Scripts” in Chapter 5. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Pascal—Pascal Compiler 
Pascal [ option... ][ file... ] 


Compiles the specified Pascal source files (programs or units). You can specify zero 
or more filenames. Each file is compiled separately—compiling file Name.p creates 
object file Name.p.o. By convention, Pascal source filenames end in a “.p” suffix. 


See the MPW Pascal 2.0 Reference for details of the language definition. 


Tool. 


If no filenames are specified, standard input is compiled, with output directed to the 
file p.o. You can terminate input by pressing Command-Enter. 


Nothing is written to standard output. For each input file name, object code is sent to 
the file name.o. 


Errors are written to diagnostic output. Progress and summary information is also 
written to diagnostic output if the -p option is selected. 


The following status values may be returned: 


0 Successful completion 
1 Error in parameters 
2 Compilation halted 


-b Generate A5-relative references whenever the address of a 
procedure or function is taken. (By default, PC-relative references 
are generated for routines in the same segment.) 


-C Syntax check only—no object file is generated. 


-d name=TRUE | FALSE 
Set the compile time variable name to TRUE or FALSE. 


-e errLogFile Write all errors to the error log file errLogFile. A copy of the error 
report will still be sent to diagnostic output 
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-i pathname(,pathname]... 


-k prefixpath 


-mc68020 
-mc68881 


-0 0objName 


“Pp 


-r 
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Search for include or USES files in the specified directories. 
Multiple -i options may be specified. At most 15 directories will be 
searched. The search order is as follows: 


1. In the case of a USES filename, if no prior $U filename was 
specified, the filename is assumed to be the same as the unit 
name (with a “.p” appended). 

2. The filename is used as specified. If a full pathname is given, 
then no other searching is applied. 


If the file wasn’t found, and the pathname used to specify the file 
was a partial pathname (no colons in the name or a leading 
colon), then the following directories are searched. 

3. The directory containing the current input file. 

4. The directories specified in -i options, in the order listed. 

5. The directories specified in the Shell variable {PInterfaces}. 


The source filenames specified on the command line must include 
any relevant prefixes. 


Put the files specified in S$LOAD commands in the directory 
specified by prefixpath. 


Generate code to take advantage of the MC68020 processor. 
Generate code to take advantage of the MC68881 coprocessor. 


Specify the pathname for the generated object file. If objName 
ends with a colon (:), it indicates a directory for the output file, 
whose name is then formed by the normal rules (that is, 
inputFilename.o). If the source filename contains a pathname, it is 
stripped off before objName: is used as a prefix. If objName does 
not end with a colon, the object file is written to the file objName. 
(in this case, only one source file should be specified.) 


Turn on overflow checking. (Warning: This may significanuy 
increase code size.) 


Supply progress and summary information to diagnostic output, 
including Compiler header information (copyright notice and 
version number), module names and code sizes in bytes, and 
number of errors and compilation time. 


Suppress range checking. 


Report compilation time to diagnostic output. The -p option also 
reports the compilation time. 


Initialize local and global data to the value $7267. 


Turn off peephole optimizer. 


-y pathname Put the Compiler’s temporary intermediate (“.0.i”) files in the 
directory specified by pathname. 


-Z Turn off the output of embedded procedure names in the object 
code. This option is equivalent to specifying {$D-} in the source 
eode:.: 

Examples Pascal Sample.p 


Compiles the Sample program provided in the PExamples folder. 


Pascal Filel.p File2.p -r 


Compiles Filel.p and File2.p, producing object files Filel.p.o and File2.p.o, and 
performing no range checking. 


Note Listing files are not produced directly by the Compiler. Refer to the PasMat and 
PasRef tools. 


Availability The Pascal Compiler is available as part of a separate Apple product, MPW Pascal. 


‘N 


See also PasMat and PasRef commands. 
MPW Pascal 2.0 Reference. 
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Syntax 


Description 


Type 


Input 


Output 


PasMat—Pascal program formatter 
PasMat [ option... ] [ inputfile [ outputfile}) 


Reformats Pascal source code into a standard format, suitable for printouts or 
compilation. PasMat accepts full programs, external procedures, blocks, and groups 
of statements. 


Note: A syntactically incorrect program causes PasMat to abort. If this happens, the 
generated output will contain the formatted source up to the point of the error. 


PasMat options let you do the following: 
O Convert a program to uniform case conventions. 


O Indent a program to show its logical structure, and adjust lines to fit into a specified 
line length. 


GQ Change the comment delimiters (* *) to { }. 


OC Remove the underscore character ( _ ) from identifiers, rename identifiers, or 
change their case. 


O Format include files named in MPW Pascal include directives. 


PasMat specifications can be made through PasMat options or through special 
formatter directives, which resemble Pascal Compiler directives, and are inserted 
into the source file as Pascal comments. PasMat’s default formatting is 
straightforward, and does not require you to use any options. The best way to find out 
how PasMat formats something is to try out a small example and see. 


See Appendix K of the manual MPW Pascal 2.0 Reference for details of PasMat 
directives and their functions. The first dialog box of the Pascal Commando dialog is 
reproduced here for your convenience. 


Tool. 
If no input files are specified, standard input is formatted. 


If no output file is specified, the formatted output is written to standard output. Refer 
to “Limitations” below for more information about PasMat’s treatment of errors in 
the source. 
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Diagnostics 


Status 


Options 


The following errors are detected and written to diagnostic output: 


QO In general, premature end-of-file conditions in the input are not reported as 
errors, to accommodate formatting of individual include files, which may be only 
program segments. There are cases, however, where the include file is a partial 
program, which PasMat interprets and reports as a syntax error. 


O There is a limit on the number of indentation levels that PasMat can handle. If this 
limit is exceeded, processing will abort. This problem should be exceedingly rare. 


O If a comment would require more than the maximum output length (150) to meet 
the rules given, processing will abort. This problem should be even rarer than 
indentation level problems. 


If a syntax error in the input code causes formatting to abort, an error message will 
give the input line number on which the error was detected. The error checking is not 
perfect—successful formatting is no guarantee that the program will compile. 


PasMat may return the following status values: 


0 Normal termination 
1 Parameter or option error 
2 Execution terminated 


Most of the following options modify the initial default settings of the directives 
described in Appendix K of the MPW Pascal 2.0 Reference. 


-a Set a- to disable CASE label bunching. 


-b Set b+ to enable IF bunching. 


Pasmat Options 


Spacing Miscellaneous 
1/0 Specifications... }/—7 None around ops [No formatting 
identifier Handling... )|~] None around := C (* *) changed to {} 


(] None after commas||( Align VAR colons 


C) IF's indenting 3 


&) FOR/WHILE/WITH's ||] Procedure bodies Grouping 
(X] CASE label's (C Between BEGIN/END||() Assignment/Calls 
(] ELSE/IF on new line||/( Fields under id (J Formal parameters 


([] BEGIN on same line Tabbing value [El] C) “Smart" grouping 


(] THEN on new IIne C) Separate CASE tags 


Command Line 
oe | 
Help : ; ; Cancel 
Reformats Pascal source into a standard format, suitable for printouts or 


compilation. Accepts full programs /units, procs, blocks, and statements. ‘an Pasmat =i 


Most options should be #embedded* in source and NOT specified here! 


-body Set body+ to align procedure bodies with their enclosing 
BEGIN/END pair. 


-C Set c+ for placement of BEGIN on same line as previous word. 
-d Set d+ to enable the replacement of (* *) with {} comment 
delimiters. 
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-€ 


-entab 


-f 


a) 


-h 


Set e+ to capitalize identifiers. 


Replace runs of blanks with tabs. The tab value is determined by the 
-t option or current t=” directive (not by the file’s tab setting). 


Set f- to disable formatting. 
Set g+ to group assignment and call statements. 


Set h- to disable FOR, WHILE, and WITH bunching. 


-i pathnamel,pathname )... 


-in 


-k 
l 


-list listingFile 


“fl 


-O width 


“P 


Search for include files in the specified directories. Multiple 

-i options may be specified. At most 15 directories will be searched. 
The search order for includes is specified under the description of 
the -i option for the Pascal command. (Note, however, that Uses 
are not processed by PasMat.) 


Set in+ to process Pascal Compiler includes. This option is implied 
if the -i option is used. 


Set k+ to indent statements between BEGIN/END pairs. 
Set I+ for literal copy of reserved words and identifiers. 


Generate a listing of the formatted source. The listing is written to 
the specified file. 


Set n+ to group formal parameters. 


Set the output line width. The maximum value allowed is 150. The 
default is 80. 


Display version information and progress information to 
diagnostic output. 


-pattern =pattern=replacement= 


PasMat 


Process includes (-in) and generate a set of output files with exactly 
the same include structure as the input, but with new names. The 
new output filenames and include directives are generated by 
editing the input (or include) filenames according to the pattern 
and replacement strings. Pattern is a pathname to be looked for in 
the input file and in each include file (the entire pathname is used, 
and case is ignored). If the pattern is found, it is replaced by the 
replacement string. The result is a new pathname, which becomes 
the name for an output file. For example, 


PasMat -pattern =OldFile=NewFile= 


replaces each name containing the string “OldFile” with the string 
“NewFile”. 


Note: Any character not contained in the pattern or replacement 
strings can be used in place of an equal sign. Special characters 
must be quoted. (See “Example” below.) 


“q 
-r 
-rec 


-S renameFile 


-t tab 


“u 


"Lg 


Set q+ not to treat the ELSE IF sequence specially. 
Set r+ to make reserved words uppercase. 
Indent a RECORD'’s field list under the record identifier. 


Rename identifiers. RenameFile is a file containing a list of 
identifiers and their new names. Each line in this file contains two 
identifiers of up to 63 characters each: The first name is the 
identifier to be renamed; the second name will replace ail 
occurrences of the first identifier in the output. There must be at 
least one space or tab between the two identifiers. Leading and 
trailing spaces and tabs are optional. The case of the first identifier 
doesn’t matter, but the second identifier must be specified exactly 
as it is to appear in the output. The case of all identifiers not 
specified in the renameFile is subject to the other case options 
Ce, -l, -u, and -w) or their corresponding directives. Reserved 
words cannot be renamed. 


Set the tab amount for each indentation level. If the -entab option 
is also specified, tab characters will actually be generated. The 
default tab value is 2. 

Rename all identifiers based on their first occurrence in the source. 
Specifications in the rename (-s) file always have precedence over 
this option—that is, the identifier’s translation is based on the 
rename file rather than on the first occurrence. 

Set v+ to put THEN on a separate line. 

Set w+ to make identifiers uppercase. 

Set x+ to suppress space around operators. 

Set y+ to suppress space around :=. 


Set Z+ to suppress space after commas. 


Set :+ to align colons in VAR declarations (only if a j PasMat 
directive in the source specifies a width). 


Set @+ to force multiple CASE tags onto separate lines. 


Set #+ for “smart” grouping of assignment and call statements. 
Grouped assignment and call statements on an input line will 
appear grouped on output. 


Note: Because # is the Shell’s comment character, this option must 
be quoted on the command line. 


Set _+ for “portability” mode (underscores are deleted from 
identifiers). 
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All options except for -list, -pattern, -s, and -entab have directive counterparts. It’s 
recommended that you specify the options as directives in the input source so that 
you won't have to specify them each time you call PasMat. 


{PasMatOpts} variable: You can also specify a set of default options in the exported 
Shell variable {(PasMatOpts}—PasMat processes these options before it processes the 
command line options. {PasMatOpts} should contain a string (maximum length 255) 
specifying the options exactly as you would specify them on the command line. The 
exception is command-line quoting, which should be omitted. Also note that the 
options -pattern, -list, -s, and -i, which require a string parameter, can be specified 
only on the command line. For example, you can define {PasMatOpts} to the Shell 
(perhaps in the UserStartup file) as follows: 


Set PasMatOpts "=n -u -r -d ~entab -# -o 82 -t 2" 
Export PasMatOpts 


The entire definition string must be quoted to preserve the spaces. 


As an alternative to specifying the options directly, you can indicate that the options 
are stored in a file, by specifying the file’s full pathname prefixed with the character *: 


Set PasMatOpts "“pathname" 
Export PasMatOpts 


PasMat will now look for the default options in the specified file. The lines in this file 
can contain any sequence of command-line options (except for -pattern, -list, -s, 
and -i), grouped together on the same or separate lines. You can comment the lines 
by placing the comment in braces ({...}). A typical options file might appear like this: 


n {group fermal params on same line} 

-u {auto translation of id's based on lst occurrence} 
=r {uppercase reserved. words} 

-d {leave comment braces alone} 

-entab {place real tabs in the output} 

~-# {smart grouping} 

-o 82 {output line width} 

-t 2 {indent tab value} 


(Except for the tab value, this example shows the recommended set of options.) 


If PasMat does find a default set of options, then those options will be echoed as part 
of the status information given with the -p option. 


PasMat 


Example 


Limitations 


Availability 


See also 


Pasmat -n -u -r -d -pattern "==formatted/="" Sample.p @ 
“formatted/Sample.p" 


Formats the file Sample.p with the -n, -u, -r, and -d options, and writes the output to 
the file “formatted/Sample.p”. Includes are processed (-pattern) and each Pascal 
Compiler $I include file causes additional output files to be generated. Each of these 
files is created with the name “formatted//filename”, where filename is the filename 
specified in the corresponding include. (The -pattern parameter contains a null 
pattern (==) with “formatted/” as a replacement string—a null pattern always matches 
the start of a string.) 


Care must be taken when a command line contains quotes, slashes, or other special 
characters that are processed by the Shell itself. In this example, we used the slash 
character, so the strings containing it had to be quoted. 


PasMat has the following limitations: 

OQ The maximum length of an input line is 255 characters. 
O The maximum output line length is 150 characters. 

O The input files and output files must be different. 
Oo 


Only syntactically correct programs, units, blocks, procedures, and statements are 
formatted. This limitation must be taken into consideration when separate include 
files and conditional compiler directives are to be formatted. 

CG The Pascal include directive should be the last thing on the input line if includes are 
to be processed. Includes are processed to a maximum nesting depth of five. All 
includes not processed are summarized at the end of formatting. (This assumes, of 
course, that the in directive/option is in effect.) 


Q The identifiers CYCLE and LEAVE are treated as reserved Pascal keywords by 
PasMat They are treated as two loop control statements by Pascal unless explicitly 
declared. 


PasMat is available as part of a separate Apple product, MPW Pascal 2.0. 


Pascal and PasRef commands. 
Appendix K of the MPW Pascal 2.0 Reference. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


PasRef—Pascal cross-referencer 


PasRef [ option... ] [ sourceFile... ] 


Reads Pascal source files, and writes a listing of the source followed by a cross- 
reference listing of all identifiers. Each identifier is listed in alphabetical order, 
followed by the number of the line on which it appears. Line numbers can refer to the 
entire source file, or can be relative to individual include files and units. Each 
reference indicates whether the identifier is defined, assigned, or simply named (for 
example, used in an expression). 


See the MPW Pascal 2.0 Reference for details of the Pascal language. The first dialog 
box of PasRef’s Commando dialog is reproduced here for your convenience. 


Identifiers may be up to 63 characters long, and are displayed in their entirety unless 
overridden with the -x directive. Identifiers may remain as they appear in the input, 
or they can be converted to all lowercase (-1) or all uppercase (-u). 


For include files, line numbers are relative to the start of the include file; an 

additional key number indicates which include file is referred to. A list of each include 
file processed and its associated key number is displayed prior to the cross-reference 
listing. 


Uses declarations can also be processed by PasRef (their associated $U filename 
compiler directives are processed as in the Pascal Compiler). These declarations are 
treated exactly like includes, and, as with the Compiler, only the outermost Uses 
declaration is processed (that is, a used unit’s Uses declaration is not processed). 


As an alternative to processing Uses declarations, PasRef accepts multiple source 
files. Thus you cross-reference a set of main programs together with the units they use. 
All the sources are treated like include files for display purposes. In addition, PasRef 
checks to see whether it has already processed a file (for example, if it appeared twice 
on the input list, or if one of the files already used or included it). If it has already 
been processed, then the file is skipped. 


Tool. 


If no filenames are specified, standard input is processed. Unless the -d option is 
specified, multiple source files are cross-referenced as a whole, producing a single 
source listing and a single cross-reference listing. Specifying the -d option is the same 
as executing PasRef individually for each file. 


All listings are written to standard output. Form feed characters are placed in the file 
before each new source listing and its associated cross reference. Pascal $P (page 
eject) compiler directives are also processed by PasRef, which may generate 
additional form feeds in the standard output listing. 


Parameter errors and progress information are written to diagnostic output. 


PasRef may return the following status values: 


0 Normal termination 
1 Parameter or opuion error 
2 Execution terminated 
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Options -a Process all files even if they are duplicates of ones already 
processed. The default is to process each (include) file or used unit 
only once. 


-C Do not process a unit if the unit’s filename is specified in the list of 
files to be processed on the command line, or if the unit has already 
been processed. 


Pasref Options 

nda chlBn taht EEO PTE SS 

@ Files to Href... © Redirect Standard Japut 
———— 


Click for list... 


Output 


Miscellaneous Error 


f& Includes oO Object Pascal ae | 


J uses C Distinct 


Progress 
Search Paths...}}/[ Unique USES 0 3 Display Options... 
Command Line 
we (tencel 
Reads Pascal source files and writes listing of source followed by a Cancel 
cross-reference listing of all id's to standard output. (Pasrer rorya 


-d Treat each file specified on the command line as distinct. The 
default is to treat the entire list of files as a whole, producing a single 
source listing and a single cross-reference listing. This option is the 
same as executing PasRef individually for each specified file. 


-i pathname [,pathname }... 
Search for include or Uses files in the specified directories. Multiple 
-i options may be specified. At most 15 directories will be searched. 
The search order is specified under the description of the -i option 
for the Pascal command. 


-1 Display all identifiers in the cross-reference table in lowercase. This 
option should not be used if -u is specified, but if it is, the -u is 
ignored. 


-ni | -noincludes 
Do not process include files. (The default is to process the include 
files.) 


-nl | -nolisting 
Do not display the input source as it is being processed. (The 
default is to list the input.) 


-nolex Do not display the lexical information on the source listing. See the 
“Example” section for further details. 


-nt | -nototal Do not display the total line count in the source listing. This option 
is ignored if no listing is being generated (-n). 
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-n{u] | -nouses 
Do not process USES declarations. (The default is to process USES 
declarations.) If -nu is specified, then the -c option is ignored. 


-O The source file is an Object Pascal program. The identifier OBJECT 
is considered as a reserved word so that Object Pascal declarations 
may be processed. The default is to assume the source is not an 
Object Pascal program. 


-p Write version and progress information to diagnostic output. 


-S Do not display include and USES information in the listing or cross 
reference, and cross-reference by total source line number count 
rather than by include-file line number. 


-t Cross-reference by total source line-number count rather than by 
include-file line number. This option can be used if you are not 
interested in knowing the positions in included files. However, the 
include information is still displayed (unless -s, -ni, or -nu is 
specified). This option is implied by the -s option. 


-u Display all identifiers in the cross-reference table in uppercase. 
This option should not be used if -1 is specified. 


-w width Set the maximum output width of the cross-reference listing. This 
setting determines how many line numbers are displayed on one 
line of the cross-reference listing. It does not affect the source 
listing. Width can be a value from 40 to 255; the default is 110. 


-x width Set the maximum display width for identifiers in the cross-reference 
listing. (The default is to set the width to the size of the largest 
identifier cross-referenced.) If an identifier is too long to fit in the 
specified width, it is indicated by preceding the last four characters 
with an ellipsis (...). Width can be a value from 8 to 63. 


Normally, both include files and Uses declarations are processed. The - 
noincludes option suppresses processing of includes. The -nouses option 
suppresses processing of USES. 


Omitting the -nouses option causes PasRef to process a USES declaration exactly as 
does the Pascal Compiler. However, you may want to cross-reference an entire 
system, including all of the units of that system. Processing the units through the USES 
declaration would cause only the Interface section of each unit to be processed. If you 
use the -nouses option, then USES will not be processed and each unit from the 
parameter list can be cross-referenced, treating the entire list as a single source. 


PasRef can also cross-reference all the units of a program while still expanding other 
units not directly part of that program, such as the Toolbox units. If you wish to do 
this, use the -c option. With the -c option, if the ($U interface) filename is the same as 
one of the filenames specified on the parameter list, then the unit will not be 
processed from the USES declaration, because its full source will be Cor has been) 
processed. 
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Example 
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To summarize, you have the following choices: 


OG Don't process the USES declarations, and specify a list of all files you want to 


process, by using the -nouses option. 
Q Process only the Interfaces through the USES declarations (like the Compiler), by 
omitting the -nouses option. 


O Process some of the units through the USES declarations and other units as full 
sources, by specifying the -c option. 


In all cases where a list of files is specified, no unit will ever be processed more than 
once (unless the -a option is given). 


Pas 


Ref -nu -w 80 Memory.p > Memory.p.Xref 


Cross-references the sample desk accessory Memory.p and write the output to the file 
Memory.p.Xref. No USES declarations are processed (-nu). The following source 


and 


{ 


} 


cross-reference listings are generated: 


File Memory.p 
Copyright Apple Computer, Inc. 1985-1987 


All rights reserved. 


{$D+} ( MacsBug symbols on } 
{$R-} { No range checking } 


UNIT Memory; 


INTERFACE 


USES 


MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf; 


FUNCTION DRVROpen 


(ctlPB: ParmB1lkPtr; dctl: DCtlPtr): OSErr; 
FUNCTION DRVRControl (ctlPB: ParmBlkPtr; dCtl: DCtlPtr): OSErr; 
FUNCTION DRVRStatus (ctlPB: ParmBlkPtr; dCtl: DCtlPtr): OSErr; 
FUNCTION DRVRPrime (CELPB:: ParmBlkPtr; -dCtls OCtlPtr) >; OSErr; 
FUNCTION DRVRClose (ctlPB: ParmBlkPtr; dCtl: DCtlPtr): OSErr; 


IMPLEMENTATION 
A FUNCTION DRVRCLose(ctlPB: ParmBlkPtr; dCtl: DCtlPtr): OSErr; 
A BEGIN 
IF dctl*.dCtlwindow <> NIL THEN 
BEGIN 
DisposeWindow (WindowPtr(dCtl*.dCtlWindow) ); 
dctl*.dctlWindow := NIL; 
END; 
DRVRClose := NOErr; 
A END; 


END. {of memory UNIT} 
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L. Memory.p 


-A~ 
accEvent 
accRun 
ApplicZone 
Away 


: -B- 


BeginUpdate 
BNOT 

Bold 
Boolean 
BOR - 

BSL 


-C- 
csCode 

. CSParam 
ctlPB 


dctl 


DCctlPtr 


dctlRefNum 
-dCtlWindow 


etc. 
-V- 
VolName 


-W- 
what 
WindowKind 
windowpeek 
" WindowPtr 
wRect 


xxx End PasRef: 
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Each line of the source listing is preceded by five columns of information: 


Le 
2. The include key assigned by PasRef for an include or USES file. (See below.) 

3 ; ; 

4. Two indicators Cleft and right) that reflect the static block nesting level. The left 


The total line count. 


The line number within the include or main file. 


indicator is incremented (mod 10) and displayed whenever a BEGIN, REPEAT, or 
CASE is encountered. On termination of these structures with an END or UNTIL, the 
right indicator is displayed, then decremented. It is thus easy to match BEGIN, 
REPEAT, and CASE statements with their matching terminations. 


. A letter that reflects the static level of procedures. The character is updated for each 


procedure nest level (“A” for level 1, “B” for level 2, and'so on), and displayed on 
the line containing the heading, and on the BEGIN and END associated with the 
procedure body. Using this column you can easily find the procedure body for a 
procedure heading when there are nested procedures declared between the heading 
and its body. 


The cross-reference listing follows: 


144 (1) 

158 (1) 

12d. 4) 

33* ( 1) 146 ( 1) 

TSi. (-1) 

39 (1) 

90° Gay AT 

31* ( 1) 

39 (1) 

39 (1) 

143.~ (4) 

146 (1) 

19* ( 1) 20*( 1) 21*( 1) 22*( 1) 234-1) 43*( 1) 
63* ( 1) 74*( 1) 143 ( 1) 146 ( 1) 168*( 1) 173*( 1) 
19* ( 1) 20*( ly 21*( 1) 22*( 1) 23*( 1) 37*( 1) 
39 (1) 43*( 1) 50° (71) 53 (1) Sie AS) S5-¢ 2) 
63* ( 1) 65 ( 1) 67 ( 1) 68 (. 1) 74% °C 2) 11S" 4) 
142 (1) 168*( 1) 173*( 1) : 

19 «( 1) 00° 4-2) ton.) 22 2) 23 ( 1) a7 1) 
43°. ote) 63 ( 1) 74 ( 1) 168 ( 1) 173 ( 1) 

39 (1) 54 (1) 

50°. € 1) 55=( 1) 67 ( 1) 68=( 1) 142 ( 1) 

79* (1) 100 (1) 135 (21) 

149 (1) 

54= ( 1) 

54 (1) 

48 (1) Gl cf Ty LSP Ey SSC a) 

7 aay Gane 

105 id's 249 references 


Limitations 


Availability 


See also 


The numbers in parentheses following the line numbers are the include keys of the 
associated include files (shown in column 2 of the source listing). The include 
filenames are shown following the source listing. Thus you can see what line number 
was in which include file. An asterisk (*) following a line number indicates a 
definition of the variable. An equal sign (=) indicates an assignment. A line number 
with nothing following it means a reference to the identifier. 


PasRef does not process conditional compilation directives! Thus, given the “right” 
combination of $IFC’s and $ELSEC’s, PasRef’s lexical (nesting) information can be 

thrown off. If this happens, or if you just don’t want the lexical information, you may 
specify the -nolex option. 

PasRef stores all its information on the Pascal heap. Up to 5000 identifiers can be 


handled, but more identifiers will mean less cross-reference space. A message is 
given if PasRef runs out of heap space. 


Note: Although PasRef never misses a reference, it can infrequently be fooled into 
thinking that a variable is defined when it actually isn’t One case where this happens 
is in record structure variants. The record variant’s case tag is always flagged as a 
definition Ceven when there is no tag type) and the variant’s case label constants Gf 
they are identifiers) are also sometimes incorrectly flagged depending on the 
context. (This occurs only in the declaration parts of the program.) 


The identifiers CYCLE and LEAVE are treated as reserved Pascal keywords by PasRef. 
These are treated as two loop control statements by Pascal unless explicidy declared. 


. PasRef is available as part of a separate Apple product, MPW Pascal 2.0. 


Pascal command. 
MPW Pascal 2.0 Reference. 
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Syntax 


Description 


Type 

Input 
Output 
Diagnostics 


Status 


Option 


Examples 


See also 
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Paste—replace selection with Clipboard contents 


Paste [-c count] selection { window ] 


Finds selection in the specified window and replaces its contents with the contents of 
the Clipboard. If no window is specified, the command operates on the target window 
(the second window from the front). It’s an error to specify a window that doesn’t 
exist. ; 

For a definition of selection, see “Selections” in Chapter 6; a summary of the - 
selection syntax is contained in Appendix B. 


Built-in. 


None. 
None. 
Errors are written to diagnostic output. 


The following status values may be returned: 


0 At least one instance of the selection was found 
1 Syntax error 
2 Any other error 


-c count For a count of 7, replace the next 1 instances of the selection with 
the contents of the Clipboard. 


Paste § 


Replaces the current selection with the contents of the Clipboard. This command is - 
like the Paste item in the Edit menu, except that the action occurs in the target 
window. 


Paste /BEGIN/:/END/ 


Selects everything from the next BEGIN to the following END, and replaces the 
selection with the contents of the Clipboard. © 


Copy, Cut, and Replace commands. 
“Edit Menu” in Chapter 3. 
“Selections” in Chapter 6. 


Syntax 


Description 


Type 
Input 
Output 


Diagnostics 


' Status 


Options 


Example 


See also 


PerformReport—generate a performance report 


PerformReport [ option...] 


PerformReport reads a link map file and a performance data file and produces a 
report that relates the performance data to procedure names. The input files are both 
text files and are distinguished as separate options. For a full discussion of MPW’s 
perounanee measurement tools, see Chapter 12. 


- Tool. 


Standard input is not processed. 
The report file is written to standard output 


If no errors are detected, PerformReport runs silently. Errors and warnings are written 
to the diagnostic output file. Progress and summary information is also written to the 
diagnostic output if the -p option is specified. ; 


The following status values may be returned: 


0 No errors 

1 Warning issued 

2 Error encountered . 

3. ‘-Heap error, usually insufficient memory 


-a Produce a listing of all procedures Cin segment order). (The default 
is to produce only a partial listing sorted by the number of possible 
hits.) 


-l fileName Read the link map of the file named fileName. 


-m fileName _ Read the performance data file named fileName. The default name 
~ is Perform.out. 


-n NN Show the top MN procedures. The default is 50. 
-—p Write progress and summary information to the diagnostic output 
file. 


Catenate "{MPW}ROM.Maps:MacIIROM.map >> myFileName 
PerformReport -m myFileName > myReport 


Adds the ROM map file to the end of the link map fle, myFileName. Reads the files 
myFileName and Perform.out and writes the output to myReport. 


Chapter 12, “Performance Measurement Tools.” 
MPW Pascal 2.0 Reference. 
MPW C 2.0 Reference. 
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Syntax 


Description 


Type 


Input 
Output 
Diagnostics 


Status 


Options 


iI-148 Print 


Print [ option... ] (file... ] 


Prints text files on the currently selected printer. (Printers are selected with the 
Chooser desk accessory.) One or more files may be printed. 


Note: Print does not support automatic font substitution. To print in a font other than 
that indicated in the resource fork of the file where the MPW editor stores font 
information, use the -font option. 


Important: Print requires the printer drivers available on version 1.0 (or later) of the 
Printer Installation disk. 


Tool. 


If no files are specified and if input has been redirected to standard input, Print reads 
from standard input. You can terminate input by pressing Command-Enter. 


All output goes to the currently selected printer. Print sends no output to standard 


output 


Errors and warnings are written to diagnostic output. If the -p option is specified, 
progress and summary information is also written to diagnostic output 


The following status values may be returned: » 


QO  . Successful completion 
1 Parameter or option error 
2 Execution error 


Note: You can also apply the Print options to the Print Window/Print Selection menu 
item by including them in the exported Shell variable {PrintOptions}. (PrintOptions! 
is Originally set to '-h' in the Startup file. 


-b . Print a eoundee border around the printable area of the page. 
Headers, if specified with the -h option, are separated from the 
body text by an extra line. 


-b2 Print an alternate form of the above border, in which the header 
appears above and outside the border. 


-clopies] n Print 7 copies of the file or selection. 


-f{[ont] name 


-ff string 


-from 7 

-h 

-hflont] name 
-hs[ize] n | 


-l[ines] n 


-Isn 


Print using the font identified by name (for example, Courier). The 
default is the font indicated in information in the resource fork of 
the file, if present, and otherwise Monaco 9. (See also the -size 
option.) 


Note: Printing with a font that is not directly supported by the 


printer is significantly slower than printing with a built-in font. 


Print Options 


-Border 


~Header —Farmat te ere 
. i 
| (7 Print Header lke Setting | @ None O Single © Double | 
| C] Use Mad. Date | Lines/Page | Wecia Panik. 
Title 


i Line Spacing | Input 
i Font i 


Bill Font Size | Error 


Font! 


(J Show Progress PostScript... 


Command Line 
ae ara 
Print text {les on the currently selected printer , Cancel 

cc 


Specifies a string that will be treated like a form feed character if it is 
encountered at the beginning of a line. If the string is the only item 
on the line, that line will be omitted. If the string is followed by 
additional characters on the line, the additional characters will be 
printed on the first line of the new page. . 


Print pages starting from page number 7. The default is to start with 


the first page of the file. 


Print page headers at the top of each page. The header indicates the 
time of printing, the name of the file, and the page number. 


Specify the font to be used in headers (-h option). The default is the 
font used in the file. 


Specify the font size to be used in headers. The default is 10. 


Print (at most) n lines per page. Line spacing is adjusted so that the 
full page is used. If both -l and -Is are specified, the -1 option takes 
precedence. 


Set line spacing. A value of 1 indicates normal (single) spacing (the 
default), 2 indicates double-spacing, and so on. Fractional values 
are permitted. 


Print the file’s last modified date, rather than the date and time of 
printing, in the header Cif headers are specified). 


Turn on line numbering; numbers appear to the left of the printed 
text. 
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-nw 7 


-r 


-slize] n 


-tlabs] n 


-title name 


-ton 


Specify the width of the line number (-n) field in characters. (The 


default is value is 5.) Negative values for n cause the field to be zero- 


padded. The valid range of values is -10 to 10. 


Write progress information to diagnostic output, indicating which 


files are printing and the number of lines and pages printed. 


Number the pages of the file, beginning with n. (By default, page 
numbers start with 1.) 


Set print quality on the Image Writer. quality is one of the following: 
strings: 

high standard draft 

Note: This option is ignored when printing on the LaserWriter. 


Output pages to the printer in reverse order. This option eliminates 
the need to reorder pages on the LaserWriter. 


Print using the font size identified by n. The default is to use the font 
size indicated in the resource fork of the file, if present: otherwise, 
the default size is 9. 


Expand tabs, using the indicated tab setting. If this option isn’t 
specified, the tab setting is taken from the resource fork of the file, if 
present; otherwise, the tab setting is taken from the {Tab} variable. 


If printing page headers (with -h), use name as the title. (The default 
is to use the filename.) 


Print pages up to page n. (The default is to print to the last page of 
the file.) 


The following options control the page margins. 7 is the margin width in inches. 


-tm 71 


-bm 71 


-Imn 


Examples 


See also 
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Print 


-rm 7 


Top margin. (Default = 0 inches) | 
Bottom margin. (Default = 0 inches) 
Left margin. (Default = 0.2778 inch, for 3-hole punched pages) 


Right margin. (Default = 0 inches) 


Print -h -size 8 -ls 0.85 Startup UserStartup 


Prints the files Startup and UserStartup with page headers, using Monaco 8 and 
compressing the line spacing. 


Print -b -hf helvetica ene 12 -r print.p 


Prints the “print.p” source file with borders, with headers in Helvetica 12, and with 
pages in reverse order. 


Print menu item in “File Menu,” Chapter 3. 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


ProcNames —display Pascal procedure 
and function names 


procnames [option ... ] [ file... ] 


ProcNames is a Pascal utility that accepts a Pascal program or unit as input and 
produces a listing of all its procedure and function names. The names are shown 
indented as a function of their nesting level. The nesting level and line number 
information is also displayed. 


ProcNames can be used in conjunction with the Pascal “pretty-printer” PasMat when 
that utility is used to format separate include files.For that case, PasMat requires that 
the initial indenting level be specified. This level is exactly the information provided 
by ProcNames. 


The line number information displayed by ProcNames exactly matches that 
produced by the Pascal cross-reference utility PasRef (with or without USES 
declarations being processed), so ProcNames may be used in conjunction with the 
listing produced by PasRef to show just the line numbers of every procedure or . 
function header. 


Another possible use for the ProcNames output is to use the line number and file 
information to find procedures and functions quickly with Shell editing commands. 


Tool. 


The file parameters specify a list of Pascal source file names to be processed. 
Standard input is processed if no filenames are specified. Unless the -d option is 
specified, the entire list of files is treated as a single group of files to be processed as a 
whole, producing a single procedure/function summary. Specifying the -d option is 
equivalent to executing ProcNames individually for each specified file. 


The procedure/function name listing is written to the standard output file. Form feed 
characters are placed in the file. before each new list (unless the -e option is 
specified). 


Errors are written to diagnostic output. 


ProcNames may return the following status values: 


0 Normal termination 
1 Parameter or option error: 
2 Execution terminated 
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Options 
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-d 


-€ 


-f 


Do not process a used unit if the unit’s $U interface filename is 
specified inthe list of files to be processed. This option has the same 
effect on the line numbering as does the -c option inthe PasRef 
utility. 


Reset total line-number count to 1 on each new file. If a list of files is 
specified, then the total line number count may either start at 1 or 
continue from where it left off in the previous file. The default is to 
agree with the listing produced by PasRef when it processes a list of 
files,that is, to continue the count. However, if you want ProcNames 
to treat each file independently, you may specify the -d option so 
that the total line number count is reset to 1 before each file is 
processed. 


Suppress page eject (form feed) between each procedure/function 
listing. 


PasMat format compatibility mode. The default lists the procedure 
and function names as a function of their Pascal Compiler 
indenting level. However, for indenting purposes only, a special 
case is made of level 1 procedures in the Implementation section of 
a unit.PasMat formats these procedures indented under the word 
Implementation. Thus they are indented as if they were level 2 
procedures. If you intend to use the level information for PasMat, 
then you should specify the -f option. 


_ -l pathname [,pathname }... 


-n 


-O 


-u 


ProcNames 


Search for include or USES files in the specified directories. 
Multiple -i options may be specifi ed. At most 15 directories will be 
searched. The search order is specified under the description of the 
-i option for the. Pascal command. 


Suppress all line number and level information in the output 
display. Only the procedure and function names will be shown 
appropriately indented. ° 


The source file is an Object Pascal program.The identifier OBJECT 


is considered as a reserved word so that Object Pascal declarations 
may be processed. The default assumes that the source is an Object 
Pascal program. 


Display version information and progress information in the 
diagnostic file. 


Process USES declarations. The only reason you would need to 


process USES declarations with ProcNames would be to make the 
line number information agree with a PasRef listing that also 
contains processed USES declarations. The default does not 
process the USES declarations because they have no effect on the 
procedure name listing, only .the associated line numbers. Thus, if 
you specify the -m option to suppress the line number information, 
it makes no sense to process USES declarations, so the -u option will 
be ignored when the -n option is specified. 


Examples 


Limitations 


procnames Memory.p >names 


Lists all the procedures and functions for the Pascal program Memory.p and writes 
the output to the file “names”. The listing below is the output generated in the 
“names” file. 


Procedure/Function names for Memory.p 


11 11 QO Memory {Main} Memory.p 
37 37 1 RsrcID 

43 43 ‘ DRVROpen 

63 63 1 DRVRClose 
74 74 1 DRVRControl 

76 76 2 DrawWindow 

83 «83 3 PrintNum 

93 93 3 Get VolStuff 
108 108 3 PrtRsrcstr 
168 168 1 DRVRPrime 

Li3- 93 1 DRVRStatus 


x** End ProcNames: 11 Procedures and.Functions - 


The first two columns on each line are line number information. The third column is 
the level number. The first column shows the line number of a routine within the total 
source. The second.column shows the line number within an include file (include 
files are always processed). As each include file changes, the name of the file from 
which input is being processed is shown along with the routine name on the first line 
after the change in source.Segment names (from Pascal Compiler $S directives) are 
similarly processed. These are shown enclosed in square brackets (the blank segment 
name is shown as "{Main]"). 


Only syntactically correct programs are accepted by ProcNames. Conditional 
compilation compiler directives are not processed. 
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Syntax 


Description 


Type 

Input 
Output 
Diagnostics 


Status 


_ Options 


Examples 


See also 


‘W184 Quit 


— Quit—quit MPW 


Quit [-y | -n | -c] 


This command is equivalent to the menu item Quit Quit executes the standard quit 
procedures, asking confirmation to save modified files, close all windows, and so on. 


Miscellaneous. 


_ None. 


None. 
Errors are written to diagnostic output. 


The following status values may be returned: 


1 Syntax error 
2 Command aborted 


Note: Quit cannot return a status of 0, because if there are no errors the command 
never returns. 


-y Answer “yes” to any confirmation dialog that occurs, causing all 
modified windows to be saved before closing them. 


-n Answer “no” to any confirmation dialog that occurs, causing all 
modified windows to be closed without saving any changes. 


-C Answer “cancel” to any confirmation dialog that occurs. This 
effectively aborts the command if any windows need to be saved. 


Quit -y . 
Quits MPW answering “yes” to any dialogs such as those prompting to save files. 
Quit -c 


Quits MPW unless any confirmation dialogs occur and dialog boxes are displayed. 


Shutdown command. 


Quote—quote parameters 
Syntax Quote [-n] [ parameters... ] 


Description Quote writes its parameters, separated by spaces and terminated by a return, to 
standard output Parameters containing characters that have special meaning to the 
Shell’s command interpreter are quoted with single quotes. If no parameters are 
specified, only a return is written. 
Quote is identical to Echo except that Quote quotes parameters that contain special 
characters. Quote is especially useful when using Shell commands to write a 
command script. 
The following special characters are quoted: 
Space Tab Retum Null 


2S CLC PO MMe he LO Pee oe Oe a OY eS: Be, 


Type Miscellaneous. 
Input None. 
Output Parameters are written to standard output and are enclosed in single quotes if they 


contain special characters. 
Diagnostics None. 
Status Status value 0 is always returned. 


Option . -n Don’t write a return following the last parameter. The insertion 
point remains at the end of the output. The -n isn’t written to 
standard output. . 


Quote -155 


Examples Echo =.a 
Quote 3.a 


Sample.a Count.a My Program.a 
Sample.a Count.a ‘My Program.a' 


Echo and Quote behave slightly differently for parameters that contain special 
characters. The first line above was produced by Echo; the second by Quote. 


Quote Notice what happens to single quotes: mee Fm tt 
Notice what happens to single quotes: '--'d''--' 


Because single quotes can’t appear within single quotes, they are replaced with 'd" 
which closes the original single quote, adds a literal quote, and reopens the single 
quotes. 


For file In =.a 
Quote Print "(file}" 
End 


Print Sample.a 
Print Count.a 
Print 'My Program.a' 


The For loop shown above-writes a Print command for each file that matches the 
pattern =.a. These commands can then be selected and executed. Notice the quotes 
in the last Print command. 


See also ‘Echo and Parameters commands. 
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Syntax 


Description 


Type 

Input 
Output 
Diagnostics 


Status 


Options 


Rename—rename files and directories 
Rename [-y | -n | -c] name newName 


The file, folder, or disk specified by name is renamed newName. A dialog box 


_ requests a confirmation if the rename would overwrite an existing file or folder. The 


-y, -M, or -c options can be used to avoid this interaction. 


Note: You can’t use the Rename command to change the directory a file is in. To do 
this, use the Move command. 


Note also: Wildcard renames in the following form will not work: 
Rename *.text =.p 


This is because the Shell expands the filename patterns “=.text” and “=.p” before 
invoking the Rename command. In order to gain the desired effect, you would need 
to execute a command such as the one shown in the fifth example below. 


Built-in. 

None. 

None. 

Errors are written to diagnostic output 


The following status values may be returned: 


0 Successful rename 
1 Syntax error . 
2 Name does not exist 
3 An error occurred 
4 Cancel was selected or implied by the -c option 
-y Answer “yes” to any confirmation dialog that may occur, causing 
- conflicting file or folder to be deleted. 
-n Answer “no” to any confirmation dialog that may occur, stopping 
the rename if newName already exists. 
-C Answer “cancel” to any confirmation dialogs, aborting the rename 


if newName already exists. 
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Examples 


See also 
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Rename Filel File2 


Changes the name of File1 to File2. 


“Rename HD:Programs:Prog.c Prog.Backup.c 


Changes the name of Prog.c in the directory HD: Prograins to Prog. nace c in the 
same directory. 


Rename Untitled: Backup: 
Changes the name of the disk Untitled to Backup. 


Rename -c Filel File2 


Changes the name of File1 to that of File2, but if a conflict occurs, cancels the 
operation and returns a status of 4. 


To perform a wildcard rename, you could execute the following set of commands: 


For Name In =.text 
( Evaluate "(Name}" =~ /(=)@l.text/ ) > Dev:Null 
Rename "{Name}" "{@1}.p" 

End 


The Evaluate command is executed only for its side effect of permitting regular 
expression processing. (The expression operator =~ indicates that the right-hand 
side of the expression is a regular expression.) Thus, you can use the regular 
expression capture mechanism, (regularExpn®n. Evaluate’s output is tossed in the 


bit bucket (Dev:Null). 


Move command. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Replace—replace the selection 
Replace [-c count] selection replacement [ window ] 


Finds selection in the specified window and replaces it with replacement If no window 
is specified, the command operates on the target window (the second window from 
the front). It’s an error to specify a window that doesn’t exist. If a count is specified, 
the Replace command will be repeated count times. 


For a definition of selection, see “Selections” in Chapter 6. A summary of the 
selection syntax is contained in Appendix B. 


You can include references to parts of the selection in the replacement by using the ® 
operator. The expression ®7, where n is a digit, is replaced with the string of 
characters that matches the regular expression tagged by ®7 in the selection. (See 
“Tagging Regular Expressions With the ® Operator” in Chapter 6.) 


All searches are by default case insensitive. To specify case-sensitive matching, set 
the {CaseSensitive} variable before executing the command. (You can do this by 
checking the Case Sensitive box in the dialogs displayed by the Find and Replace 
menu items.) 


Built-in. 

None. 

None. 

Errors are written to diagnostic outpul. 


The following status values may be returned: 


QO At least one instance of the selection was found 
1 Syntax error 
2 Any other error 


-C count Repeat the command count times. As a convenience, e (Option-5) 
can be specified in place of a number. -c replaces all instances 
of the selection from the current selection to the end of the 
document (or to the start of the document, for a backward search). 
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Examples 


See also 
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Replace -c o /myVar/ 'myVariable' Prog.p 
Replaces every subsequent instance of the selection with the string in single quotes. 


Replace -c 5 /*[ dtj+/ ''! 
Strips off all the spaces and tabs at the front of the next five lines in the file Cand 
replaces them with the null string). This action takes place in the target window. 


Set HexNum "(0-9A-F] +" 
Set Spaces "{ dt]+" 
Replace -c » /({HexNum}) ®1{Spaces}({HexNum})®2/ @®@1ldn®2 


Defines two variables for use in the subsequent Replace command, and converts a file 
that contains two columns of hex digits (such as the icon list from ResEdit) into a 
single column of hex digits. 


Find and Clear commands. 
Chapter 6. 
Appendix B. 


Replace 


Request—request text from a dialog box 
Syntax Request [ -d default] [ message...] 


Description Displays an editable text dialog box with OK and Cancel buttons and the prompt 
message. If the OK button is selected, then all text that the user typed into the dialog 
box is written to standard output The -d option lets you set a default response to the 


request. 

Type Built-in. 

Input Reads standard input for the message if no parameters are specified. 
Output Text from the dialog box is written to standard output. 


Diagnostics None. 


Status Request may return the following status values: 


0 The OK button was selected 
1 Syntax errors 
2 The Cancel button was selected 


Options -d default The editable text field of the dialog box is initialized to default. The 
default text appears in the dialog box—if the OK button is selected 
without changing the response, the default is written to standard 
output. 


Examples Set Exit 0 
Set FileName "*Request 'File to compile' -d "{Active}"'" 
If {FileName} #« "" 
Pascal "(FileName}" 2> "(WorkSheet}" 
End 
Set Exit 1 


Displays a dialog box that lets the user enter the name of a file to be compiled. Sets 
the default to be the name of the active window, as follows: 


File to compile 


See also Alert and Confirm commands. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


ResEqual—compare resources in files 


ResEqual { option] file1 file2 


ResEqual compares the resources in two files and writes their differences to standard 
output. 


ResEqual checks that each file contains resources of the same type and identifier as the 
other file; that the size of the resources with the same type and identifier are the same; 
and that their contents are the same. 


Tool. 


The filei and file2 parameters specify the two files whose resources are to be 
compared. 


Descriptions of the differences in the resources of the two files are written to standard 
output. 


The following messages appear when reporting differences: 


O In 1 but not in 2 
—the resource type and ID are displayed— 


O In 2 but not in 1 
—the resource type and ID are displayed— 


C Resources are different sizes 
—the resource type and ID are displayea— 
—the size of the resource in each file is displayed— 


O Resources have different contents 
—the resource type and ID are displayed— 
Contents of resource in file 1 at offset 
—offset to the differing bytes from the start of the resource is displayed— 
—16 bytes at the offset are displayea— 
Contents of resource in file 2 at offset 
— offset to the differing bytes from the start of the resource is displayed— 
—16 bytes at the offset are displayed— 


Parameter errors are written to diagnostic output. 


The following status values may be returned 


0 Resources match 

Z Parameter or option error 
Z Files don’t match 

3 Execution terminated 
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Option 


Example 


Limitations 


See also 


-p Write progress information to diagnostic output. 


ResEqual Options 


(—s to Compare-———— Redirection Sa 
| Resource File 1 | aes | 
| Nasource File 2 | —————-] 

(C) Progress eae 


Command Line 
a | 
Help Cancel 
ResEqual compares the resources in two files and reports the differences. 
{ Hesequat | 


Resequal Sample Sample.rsrce 


Compares the resources in Sample and Sample.rsrc, writing the results to standard 
output. 


When the contents of resources are compared and a mismatch is found, the 
mismatch and the subsequent 15 bytes are written. ResEqual then continues the 
comparison, starting with the byte following the last displayed. 


If more than 10 differences are detected in the same resource, the rest of the resource 
is skipped and processing continues with the next resource. 


Equal command. (The -r option of Equal compares the resource forks of files on a 
byte by byte basis, including the resource map.) 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Option 


Examples 


See also 


Reveri—revert to saved files 


Revert [-y ][ window...] 


Reverts the specified windows to their previously saved states. If no window is 
specified, Revert works on the target window. Revert causes a confirmation dialog box 
to appear, but you can avoid this dialog box by using the -y option to revert 
unconditionally to the last saved version of the document. 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


The following status values may be returned: 


0 No errors 

1 Parameter or option error 

2 The specified window does not exist 
3 _—A system error occurred 


-y Unconditionally revert all named windows to their previously saved 
states. 


Revert 


Displays a confirmation dialog box for reverting the target window to its last saved 
state. 


Revert ~-y “{Worksheet}" 
Reverts unconditionally to last saved worksheet. 


Close and Save commands. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Rez—Resource Compiler 
Rez [ option... ] { resourceDescriptionFile... | 


Creates the resource fork of a file according to a textual description. The resource 
description file is a text file that has the same format as the output produced by the 
Resource Decompiler, DeRez. The data used to build the resource file can come 
directly from the resource description file(s) as well as from other text files (via 
#include and read directives in the resource description file), and from other 
resource files (via the include directive). 


Rez includes macro processing, full expression evaluation, and built-in functions and 
system variables. For details of Rez, and the format of a resource description file, see 
Chapter 8. For a summary of the format of a resource description file, see 

Appendix D. 


Tool. 


Standard input is processed if no filenames are specified. 
For all input files on the command line, the following search rules are applied: 
1. Try to open the file with the name specified “as is.” 


2. If the preceding rule fails, and the filename contains no colons or begins with a 
colon, append the filename to each of the pathnames specified by the {RIncludes} 
variable and try to open the file. 


- No output is sent to the standard output file. By default, the resource fork is written to 


the file Rez.Out. You can specify an output file with the -o option. 


If no errors or warnings are detected, Rez runs silently. Errors and warnings are 
written to diagnostic output. 


Rez may return the following status values: 


0 No errors 

Error in parameters 
Syntax error in file 
I/O or program error 


Wn 
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Options 
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Rez 


-align word [longword) 


-a[ppend] 


Aligns resources along word or longword boundaries. This may 
allow the Resource Manager to load these resources faster. The 
-align option is ignored when the -a option is in effect. 


Appends Rez’s output to the output file rather than replacing the 
output file. 


Warning: Rez will overwrite any existing resource of the same type 
and ID without any warning message. Rez cannot append resources 
to a resource file that has its Read Only bit set. Also, Rez cannot 
replace a resource file that has a protected bit set, unless the -ov 
option is specified. Although it is possible to append a resource 
directly into a running system file, it is not recommended. See also 
the -ov option below. 


Rez Options 


Resource Output File—_—_—___-___— C Redeclared types ok 


| -© Rewrite resource file 
(] Make resource file read-only 
| Resource Alignment 
@Byte OWord OLongWord | 


© Merge resources into resource file | 


Type = | UL | Clprogress information 
Creator | 7??? 
| 
| 
| 


CJ OK ta replace protected resoures 


Command Line 
re | 


Help 


Rez is a tool used to compile resources. 


-c{reator] creatorExpr 


-d{efine] macro[=data | 


-i pathname) 


-O outputFile 


-OV 


Define the macro variable macro to have the value data. If data is 
omitted, then macro is set to the null string—note that this still 
means that macro is defined. Using the -d option is the same as 
writing 

#define macro [ data | 


at the beginning of the input. 


Search the following pathnames for #include files. This option 
may be specified more than once. The paths will be searched in the 
order they appear on the command line. 


rez -i (mpw)myStuff: -i hd:tools... 
Place the output in ouiputFile. The default output file is Rez.Out. 


Overrides the protected bit when replacing resources with the -a 
option. 


-plrogress] Write version and progress information to diagnostic output. 
-rd Suppress warning messages if a resource type is redeclared. 
-ro Set the mapReadOnly flag in the resource map. 

-S pathname(s) Search the following pathnames for resource include files. 


-tlype] typeExpr 
Set the type of the output file. The default value is 'APPL'. 
-u{ndef] macro Undefine the macro variable macro. This is the same as writing 


#undef macro 


at the beginning of the input. It is meaningful to undefine only the 
preset macro variables. 


Example Rez Types.r Sample r -o Sample 


Generates a resource fork for the file Sample, based on the descriptions in Types.r 
and Sample.r. 


See also DeRez and RezDet commands. 
Chapters 5 and 8. 
Standard resource type declarations in the {RIncludes} directory: 
Q Types.r 
Q SysTypes.r 
Q MPWTypes.r 
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Syntax 


Description 


Type 
Input 


Output 


RezDet—detect inconsistencies in resources 
RezDet [-b] [-q | -s | -d 1 -r | -1] resourceFile... 


If no options are specified, RezDet investigates the resource fork of each file for 
damage or inconsistencies. The specified files are read and checked one by one. 
Output is generated according to the options specified. 


RezDet checks for the following conditions: 


QO The resource fork is at least the minimum size. (There must be enough bytes to read 
a resource header.) 


Q There is no overlap or space between the header, the resource data list, and the 
resource map. There should be no bytes between the EOF and the end of the 
resource map. 


CQ Each record in the resource data list is used once and only once. The last data item 
ends exactly where the data list ends. 


CO Each item in the resource type list contains at least one reference; each sequence of 
referenced items starts where the previous resource type item’s reference list 
ended; and each item in the reference list is pointed to by one and only one 
resource type list item. 


O There are no duplicates in the resource type list. 


© Each name in the name list has one and only one reference, and the last name 
doesn’t point outside the name list. 


QO There are no duplicate names in the name list. Duplicate names cause an advisory 
warning rather than a true error. This warning is given only if the -s, -d, or -r option 
is selected. . 


OG Each reference list item points to a valid data item and either has a name list offset 
of -1 or points to a valid name list offset. 


O Bits 7 (Unused), 1 (Changed), or 0 (Unused) should not be set in the resource 
attributes. 


© All names have a nonzero length. 


Fields are displayed as hex or decimal for numeric values, or as a hex dump with 
associated printable Macintosh characters. The characters return ($O0D), tab ($09), 
and null ($00) are displayed as “4”, “A”, and *.” respectively. The same is true for a 
resource name shown as a [ext string. 


Note: RezDet does not use the Resource Manager and should not crash, no matter 
how corrupt the resource fork of the file. 


Tool. 
RezDet does not read from standard input. 


Information describing the resource fork is written to standard output (together with 
any other information generated by the -s, -d, -1, or -r option). 
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Diagnostics 


Status 


Options 


Examples 


Limitations 


Error messages go to diagnostic output. 


The following status values may be returned: 


QO No errors detected 

1 Invalid options or no files specified 

2 Resource format error detected 

3 ‘Fatal error—an I/O or program error was detected 


Only one of the following options can be used at one time: 


-qluiet] Don’t write any information to standard output. This option 
suppresses all resource file format errors normally generated. 


-s{thow] Write information about each resource to standard output. 


-d{ump] Same as -Show but also generates detailed information about 
headers, name lists, data lists, and so on. 


-rlawdump] Same as -dump but also dumps contents of data blocks, and so on. 
Note: This option can generate huge amounts of output 


-llist] List resource types, IDs, names, attributes, and resource sizes to 
standard output in the following format: 


'type' CUD,name,attributes) [size] 
The following option can be used by itself or with other options: 


-blig] Read the data for each resource into memory one resource at a 
time, instead of all at once (used for huge resource files). If RezDet 
tells you that it ran out of memory, try using this option. 


RezDet "{SystemFolder}System" 


Checks the System file for damage. 


RezDet -q Foo || Delete Foo 


Removes the file Foo if the resource fork is damaged. 


Duplicate resource name warnings are generated even if the names belong to 
resources of different types. 


The file attributes field in the resource map header is not validated. 
The Finder-specific fields in the header and resource map header are ignored. 
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Save—save windows 
Syntax Save [-a | windows...] 


Description Saves the contents of window or a list of windows to disk, without closing them. The 
-a option saves all open windows. Save without any parameters saves the target 
window (the second window from the front). 


Type Built-in. 
Input None. 
Output None. 


Diagnostics Errors are written to diagnostic output. 


Status Save may return the following status values: 


0 NO errors 
1 Syntax error 
2 Specified window does not exist 


Option -a Save all open windows. This option cannot be used when any 
windows are specified. 


Examples Save -a 
Saves all open windows. 


Save "{Active}" "{Worksheet}" 


Saves the Worksheet window and the contents of the active window. 


See also Close and Revert commands. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Search—search files for a pattern 
Search [-s | -i ] {-r] [-q] (-f file] /pattern/ [file...] 


Searches the input files for lines that contain a pattern, and writes those lines to 
standard output. If no file is given, standard input is searched. When reading from 
files, the filenames and line numbers of matching lines are prepended to each line of 
output. 


Pattern (defined in “Pattern Matching” in Chapter 6 and in Appendix B) is a regular 
expression, optionally enclosed in forward slashes (/). 


Tool. 

Standard input is read if no files are specified. 
Each matching line is written to standard output. 
Error messages are written to diagnostic output. 


The following status values may be returned: 


0 No error 

1 Syntax error 

2 Pattern not found 

-r Write the lines not matching the pattern to standard output. 

-q Write only the matching lines to standard output. Do not prepend 
filename and line number. 

-S Case-sensitive search, overriding {CaseSensitive} variable. 

-i Case-insensitive search, overriding {CaseSensitive} variable. 

-f file All lines that do not get written to standard output are written into 


this file. 
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Examples 


See also 


I-172 


Search /procedure/ Sample.p 


Searches the file Sample.p for the pattern “procedure”. All lines containing this 
pattern are written to standard output. 


Search /Export/ "{MPW)"StartUp "(MPW})"UserStartUp 
Lists the Export commands in the StartUp and UserStartup files. 


Search /PROCEDURE [a-zA-Z0-9_]*;/ "{PInterfaces}"= 

Searches for the procedures with no parameters in the Pascal interface files supplied 
with MPW Pascal. Because more than one input file is specified, a filename will 
precede each line in the output. 


Search -f file.nonmatch /pattern/ file 

All lines of “file” that contain “pattern” are written to standard output. All other lines 
will be placed in file.nonmatch. This, in effect, splits the file in two pieces, using 
“pattern” as the key. 


Search -r -f file.nonmatch /pattern/ file 

This does the opposite of the first example. All lines that do not contain “pattern” are 
echoed to standard output, and all other lines (that is, those containing “pattern”) 
are written to file.nonmatch. 


Find command. 
“Pattern Matching (Using Regular Expressions)” in Chapter 6. 


Search 


Set—define or write Shell variable 
Syntax Set [ name [ value )] 


Description Assigns the string value to the variable name. If value is omitted, Set writes the name 
and its current value to standard output. If both name and value are omitted, Set 
writes a list of all variables and their values to standard output. (This output is in the 
form of Set commands.) 


Note: To make variable definitions available to enclosed scripts and programs, you 
must use the Export command. 


Type Built-in. 
Input None. 
Output If value or both name and value are omitted, variable names and their values are 


written to standard output. 
Diagnostics Error messages are written to diagnostic output. 


Status The following status values may be returned: 


0 No error 
1 Syntax error 
Z Variable “name” does not exist 


Options None. 
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Examples 


See also 
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Set 


Set CIncludes "({(MPW}CFiles:CIncludes:" 


Redefines the variable CIncludes. 


Set CIncludes 
Displays the new definition of CIncludes. 


Set Commands d 
";,  (MPW}Tools:, (MPW}Applications:, (MPW}ShellScripts:" 


Redefines the variable {Commands} to include the directory "{MPW}ShellScripts:". 
(See Chapter 5 for a complete list of predefined variables.) 


Set > SavedVariables 
# ... other commands 
Execute SavedVariables 


Writes the values of all variables to file SavedVariables. Because the output of Set is 
actually Set commands, the file can be executed later to restore the saved variable 
definitions. This technique is used in the Suspend and Resume scripts to save and 
restore variable definitions, as well as exports, aliases, and menus. 


Export, Unexport, and Unset commands. 
“Defining and Redefining Variables” in Chapter 5. 
“The Startup and UserStartup Files” in Chapter 5. 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 


See also 


SetDirectory—set the default directory 
SetDirectory directory 


Set the default directory and add the new default directory to the Directory menu if it 
is not already present. The directory parameter must be specified. 


Note: Directory names should not contain any of the special characters shown below. 
These characters all have special meaning when they appear in menu items: 


= ae Oe Ee 


The SetDirectory script is used to implement the Set Directory menu item in the 
Directory menu. 


Script. 
None. 
None. 
Errors are written to diagnostic output. 


The following status values may be returned: 


0 Successful completion 
1 Parameter error or unable to set directory 
None. 


SetDirectory "(MPW}"CExamples: 


Sets the default directory to the CExamples: folder in the {MPW} directory, and adds 
"(MP W}"CExamples: to the Directory menu if it’s not already there. 


SetDirectory... 


Uses the Commando dialog box to select the default directory interactively. 


Directory, DirectoryMenu, and Files commands. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


SetFile—set file attributes 


SetFile [option...] file... 


Sets attributes for one or more files. The options apply to all files listed. 


Tool. 


None. 


None. 


Error messages are written to diagnostic output. 


The following status values may be returned: 
0 The attributes for all files were set 


1 Syntax error 


2 An error occurred 


-¢ creator 


-t type 


-d date 


-m date 


-l hv 
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Set the file creator. Creator must be 4 characters; for example, 


-c 'MPS ''! 


Set the file type. 7Zype must be 4 characters; for example, 


-t 'TEXT' 


Set the creation date. D@te is a string in the form 
"mm/dd/yy {| hh:mm (:ss] [AM | PM] ]" 


representing month, day, year (0-99), hour (0-23), minute, and 
second. The string must be quoted if it contains a space. A period 
(.) indicates the current date and time. 


Set the modification date: same format as above. A period (.) 
indicates the current date and time. 


Set the icon location. 4 and v are positive integer values and 
represent the horizontal and vertical pixel offsets from the upper- 
left corner of the enclosing window. 


-a attributes Set the file attributes. Attributes is a string composed of the 
characters listed below. Attributes that aren't listed remain 
unchanged. 


Locked 

Invisible 

Bundle 

System 

Inited 

On Desktop 

Shared (can run multiple times) 
Always switch launch Gf possible) 


rPenotMNwedc 


Uppercase letters set the attribute to 1, lowercase to 0. For example, 
Setfile -a vB Filename 
clears the invisible bit and sets the bundle bit. 


Note: These attributes are described in the File Manager chapter of 
Inside Macintosh. Note that setting the locked bit doesn’t prevent 
the file from being changed. 


Examples SetFile -c "MPS " -t MPST ResEqual 
Sets the creator and type for the MPW Pascal tool ResEqual. 


SetFile Foo -m "2/15/86 2:25" 
Sets file Foo’s modification date. 


SetFile Foo Bar -m 


Sets the modification date to the current date and time (the period is a parameter 
to -m, indicating current date and time). Setting the date is useful, for instance, 
before running Make. 


See also Files command. (The -1 and -x options display file information.) 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


SetPrivilege—set access privileges for folders 
on file server 


SetPrivilege [-f priv] [-d priv] {[-c pri [-o owner [-g group] [-r] [-il folder... 


SetPrivilege is equivalent to using the access privileges desk accessory. Priv is a 
character string (1, 2, or 3 characters long) that specifies privileges for the owner, the 
group, and everyone (0, g, and e, respectively). An uppercase letter enables the 
privilege, lowercase disables the privilege. If a specific character is not in the string 
then the respective privileges are not changed. 


Built-in. 
None. 
When the -i option is used, folder information is written to standard output. 


Errors are written to diagnostic output. 


The following status values may be returned: 


No error 

Syntax error 

Folder not found, or folder not an AppleShare folder 
Use is not owner; could not modify privileges 


WN © 


-O new owner Change owner of the folder to new owner. 


-g new group Change group of the folder to new group. 
-r Recursively apply changes to enclosed folders. 
-f priv See files. Set the privileges with respect to seeing files within 


folders (equivalent to read access). 


-d priv See folders. Set the privileges with respect to seeing folders and 
dierectories and listing their contents. 


-C priv Make changes. Set privileges allowing users to make changes to 
files and directories. 


-i Write folder information (owner, group, and access privileges) to 
standard output. The output is in the form of a SetPrivilege 
command. The -r option is the only option that may be used in 
conjunction with the -i option. 
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Examples 


SetPrivilege -r -f OGe -d OGe -c Oge 9 
“Server:personal:peter" 


This gives everyone in your group the ability to see files within Server: personal: peter 
without being able to change them. Anyone outside the group cannot see the files or 
folders or make changes. The owner can do everything. 


Here is the easiest way to use the SetPrivilege command: Use the -i option to get 
information on folders and edit the privileges as desired. Then execute the resulting 
command. For example, to change the privileges for Server:Private, follow these 
steps: 


ae 


Execute this command to obtain the current privileges: 


SetPrivilege -i Server:Private 
SetPrivilege Server:Private -o Joe -g Team -d OGE -f OGE -m OGE 


Note: These privileges show that Joe, the group Team, and everyone else has all 
privileges to the folder Private. 


. Now edit the output, adjusting the privileges as desired. For example, 


SetPrivilege Server:Private -o Joe -g Team -d Oge -f Oge -m Oge 


Note: Now only Joe, the owner, can see directories and files; only Joe can make 
changes. All other users have no privileges. 


. Execute the resulting command. 


SetPrivilege Il-179 


Syntax 


Description 


SetVersion—maintain version and revision number 
Setversion [ option... ] file 


Version and revision numbers for an application or MPW tool specified by file are 
assumed to be maintained in the form "ver.rev', where ver is considered a version 
number and reva revision number. These values may be displayed by an 
application’s “about box” or when an MPW tool’s -p option is used. Use SetVersion to 
independently maintain the version and revision numbers as a resource in the 
application or tool. Optionally, SetVersion can update a version and revision string 
in a source file. Pascal, C, and Rez source files are supported. 


The current version and revision values are always assumed to be in the specified file’s 
resource fork as a string resource with the resource type 'MPST’ and a resource ID of 0 
(you can use the -t and -i options to specify another resource type and ID number if 
desired). The resource will be created by SetVersion if it is not already there. The 
string always contains the characters “Version ver.rev’, where verand rev are digits. 
The version may optionally be prefixed with an arbitrary string -prefix), and the 
revision may be similarly suffixed with an arbitrary string (-suffix) for more complex 
version numbering (such as “Version x1.23B2”). 


SetVersion can perform the following functions on the version and revision values: 


Q Increment the version number by 1 Gv). 
G Set the version number to a specific value ¢sv). 
QC Increment the revision number by 1 Cr). 


CG Set the revision number to a specific value Csr). 


The 'MPST' resource attached to the application or tool is considered the location of 
the version and revision. If you attach the ‘MPST’ resource to the actual application or 
tool, it will “go” wherever the application or tool goes! Thus the application or tool 
filename is a required parameter to SetVersion. However, the values contained in the 
'MPST' resource can be used to set a corresponding string constant in a source file 
used to generate the application or tool. This feature is optional, but it should be used 
for two reasons. First, it explicitly allows the source to reflect the version and revision 
numbers in the 'MPST' resource. Second, if, for any reason, the 'MPST" resource 
cannot be accessed, the constant can be used. 
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Type 


Input 


Output 


Diagnostics 


Status 


The following Pascal code fragment illustrates how the 'MPST' resource and its 
corresponding source string constant can be used to access the version and revision 
of an MPW tool. First, in the case of Pascal, the source constant is assumed to be 
declared as follows (all the formats are discussed under “Options” below): 


CONST 
Version = '1.2'; (ver.,rev string const.} 


The following procedure can now be used to get the current version and revision numbers: 


PROCEDURE GetVerRev (VAR VerRev: Str255); 
VAR 
H: StringHandle; 
iL: Integer; 


BEGIN {GetVerRev ~ get current "ver.rev"™} 


H := StringHandle(GetResource('MPST', 0)); {Get 'MPST' rsrce } 
IF H = NIL THEN (Use string const.} 
VerRev := Version {1£ not found } 
ELSE 
BEGIN 
i := Pos('Version', H*%) + 8; {Start of ver.rev } 
VerRev := Copy(H**, i, Length(H**)-i+l); (Extract from rsrc} 
END; 


END; (GetVerRev} 


Normally, SetVersion is used with its -r option as part of a makefile to automatically 
increment the revision number each time the application or tool is rebuilt. For each 
(major) release the version number should be incremented and the revision reset to 
0. Note that when SetVersion modifies the application or tool, or updates a source 
file, the modification date is not changed. Therefore, makefiles will not be affected by 
the use of SetVersion. 


Tool. 


The /ile parameter specifies the filename of an application or tool containing the 
'MPST" string resource. 


None. 


Errors are written to the diagnostic file. 


The following status values may be returned: 


0 Normal termination 
1 Parameter or option error 
2 Execution terminated 
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Options 


l-182 


-csource file 


-d 


-fmt nf.mf 


SetVersion 


Update the string constant in the C source specified by the file. The 
constant is set to be the same as that specified by the 'MPST’ 
resource string in the application or tool. It is assumed that the 
constant is defined as a string constant in a #define, somewhere in 
the first 12800 characters (25 512-byte blocks) of the file, as follows: 


&defineAVersion "ver. rev"AAAAAAAAAA/* some comment */ 


The A’s indicate required spaces. There may be any number of 
spaces before the required comment. However, because 
SetVersion edits the line in-place, there must be enough room to 
allow for changes in the size of the version and revision 
values—otherwise an error will be reported to the diagnostic file. 
Case is ignored, and C comments are skipped, when searching for 
the characters "#defineAVersion" in the source. The -verid may be 
used to search for a different #define identifier if desired. 


Write the (updated) version and revision values contained in the 
'MPST' resource string to the diagnostic output file. 


Format the version and revision values according to the specified 
format. The format of the resource is changed only if the version 
and/or revision is actually changed (sv, -v, -sr, -r). The format is 
specified as nf.mf, where f is either of the letters D or Z, and n and 
m are integer values from 1 to 10, which specify the field widths of 
the version and revision numbers respectively. If the version or 
revision value is larger than the specified field width,.the width is 
enlarged to contain the entire value. Each field is independently 
padded up to the specified width with leading zeros or blanks 
according to the setting of f. “D” indicates leading blanks, and “Z” 
indicates leading zeros. For example, a format of 1Z.3Z for a 
version/revision value of 10.2 would be formatted as d10.002. The 
default format is 1Z.1Z. Only the version format (mf) or revision 
format (.mf, the period is required) need be specified, allowing the 
other value to format according to the default. 


SetUersion Options 


Options 
Application or MPW Tool Name Ji nisptay ( tncrement versian 


Source Files CO) Pragress (] Increment reuisian 
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Resource Attributes Sat fie 
Resource Type |MPST: 
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Rez Source 


Resaurce ID 


a ee | t ‘ 
Command Line 
| SetVersion | 
Tool or application version/revision number (“ver .rey*) maintainer. Cancel 
Generates /maintains a string resource in a tool or application. Se tersian y 


-l resid 


-prefix prefix 


-(plsource /ile 


The 'MPST' resource ID is the specified resid The default is to use a 
resource ID of 0. (The -t option may be used to specify the resource 


type.) 


Write SetVersion’s version number and the contents of the 'MPST' 
resource to the diagnostic output file. (You can use the -d option just 
to output the 'MPST" information to the diagnostic output file.) 


Set the prefix string on the version. The prefix may be any sequence 
of characters that does not end with a digit (0-9) or a blank.(A blank 
could be inserted by choosing an appropriate -fmt format with 
leading blanks for the version number.) Once the prefix is set, you 
can change it only by specifying another -prefix string. 
Alternatively, you can remove the prefix by specifying the prefix as 
a period (.). 


Update the string constant in the Pascal source specified by the /ile. 
The constant is set to be the same as that specified by the 'MPST' 
resource string in the application or tool. It is assumed that the 
constant is defined in a CONST section somewhere in the first 12800 
characters (25 512-byte blocks) of the file as follows: 


Version = 'ver.rev' ; AAAAAAAAAAAAAAAAA{ some comment } 


The A’s indicate required spaces (Spaces or tabs may surround the 
“=”), There may be any number of spaces before the required 
comment. However, because SetVersion edits the line in-place, 
there must be enough room to allow for changes in the size of the 
version and revision values—otherwise an error will be reported to 
the diagnostic file. Case is ignored, and Pascal comments are 
skipped, when searching for the “Version” identifier in the source. 
The -verid may be used to search for a different identifier if desired. 


Increment the revision by 1. 
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Example 
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-rezsource file Update the 'MPST' resource definition in the Resource Compiler 
source specified by the file. The definition is set to be the same as 
that specified by the 'MPST' resource string in the application or 
tool. It is assumed that the definition is somewhere in the first 12800 
characters (25 512-byte blocks) of the file and is specified as follows: 


type 'MPST' as 'STRA'; 
resourceA'MPST' (0) ({ 

"Version ver. rev" AAAAAAAAAAAAAA/* some comment*/ 
}3 


The A’s indicate required spaces. There may be any number of 
spaces before the required comment. However, because 
SetVersion edits the line in-place, there must be enough room to 
allow for changes in the size of the version and revision 
values—otherwise an error will be reported to the diagnostic file. 
Case is ignored, and Rez comments are skipped, when searching for 
the characters "resourceA'MPST"™ in the source. Note that, because 
this is a resource definition and destined to be placed in the 
application’s or tool’s resource fork, this option defines the actual 
string resource that SetVersion will seek in the application or tool. 
The “Version” in the string here is fixed, and not controlled by the 
-verid option. 


-sr revision Set the revision to the specified revision integer value. 


-suffix suffix Set the suffix string on the revision. The suffix may be any sequence 
of characters that does not begin with a digit (0-9). Once the suffix is 
set, it can be changed only by specifying another -suffix string, or 
removed by specifying the suffix as a period (.). 


-SV version Set the version to the specified version integer value. 


-t type Use the specified resource type instead of 'MPST". (The -i option can 
be used to specify the resource ID.) 


-V Increment the version by 1. 


-verid identifier 
Use the specified constant identifer when searching for the 
-[plsource CONST identifier or -csource #define identifier. 


setversion -d -sv 1 -r Asm -psource GlobalDcls ~rezsource Asm.r 


Increments the revision for the MPW Assembler Cr) in the resource fork of the file 
Asm. The version is fixed at 1 (sv), so that Asm will display the version and revision 
as “l.rev’ The Pascal include file, GlobalDcls, contains the Assembler’s global 
declarations, including the Version string. This include file is updated to match the 
'MPST’ resource (-psource). The resource definitions for the Assembler, in Asm.r, 
will be similarily updated (-rezsource). Finally, this command displays the new 
version of the diagnostic output file (-d). 


SetVersion 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 


See also 


Shift—renumber script parameters 


Shift { number] 


Renames the command script positional parameters {mumbert1}, {number+2}... to 
{1}, {2}, and so on. If number is not specified, the default value is 1. Parameter 0 (the 
command name) is not affected. The variables {Parameters}, {"Parameters"}, and 


{#} variables are also modified to reflect the new parameters. 
Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


The following status values may be returned: 


0 Success 
1 Syntax error 


None. 


The following script repeats a command once for each parameter: 


### Repeat - Repeat a command for several parameters ### 
# 
# Repeat command varameter... 
# Execute command once for each parameter in the 
# Parameter list. You can specify options by 
# including them in quotes with the command name. 
# 
Set cmd "{1}" 
Loop 
Shift 
Break If "{1}" == "" 
{cmd} "{1}" 
End 


Here the Shift command is used to step through the parameters. The Break command 
tells the loop when all the parameters have been used. You might, for example, use 


this Repeat script to compile several C programs with progress information: 


Repeat 'C -p' Sample.c Count.c Memory.c 


“Parameters” in Chapter 5. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 


Shutdown—shutdown or software reboot 


Shutdown [-y | -n | -c][-r] 


Quits MPW and then either shuts down or reboots the Macintosh. The default is 
shutdown. Before rebooting the computer, the system executes standard quit 
procedures, asking for confirmation to save modified files, close all windows, and so 
on. 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


The following status values may be returned: 


1 Syntax error 
2 Command aborted 


Note: Shutdown cannot return a status of 0 because if there are no errors the 
command never returns. 


-y Answer “yes” to any confirmation dialog that occurs. 

-n Answer “no” to any confirmation dialog that occurs. 

-C Answer “cancel” to any confirmation dialog that occurs. 
-r Restart the machine. 


Shutdown -y 


Reboots the machine, answering “yes” to any dialogs such as those prompting to 
save files. 


Quit command. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 


See also 


SizeWindow—set a window's size 


SizeWindow hv [window } 


Sets the size of the specified window to be h by v pixels, where h and v are 
nonnegative integers referring to the horizontal and vertical dimensions 
respectively. (Use a blank space to separate the numbers h and v on the command 
line.) The default window is the target (second from the front) window; a specific 
window can optionally be specified. If the size specified would cause the window to 
be too big or small, an error is returned. 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


SizeWindow may return the following status values: 


0 No errors 

1 Syntax error (error in parameters) 

2 The specified window does not exist 

3 ‘The h,v size specified is invalid, that is, too big or too small 


None. 


SizeWindow 200 200 
Makes the target window 200 pixels square in size. 


SizeWindow 500 100 "{Worksneet}" 


Makes the Worksheet window 500 x 100 pixels in size. 


MoveWindow, ZoomWindow, StackWindows, and TileWindows commands. 
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StackWindows—arrange windows diagonally 
Syntax StackWindows 


Description Automatically sizes and moves all of the open Shell windows so that they are 
staggered diagonally across the screen. Use Stack Windows when selecting windows 
from the Window menu; this makes dealing with many open windows easier. 


Type Built-in. 

Input None. 

Output None. 

Diagnostics Errors are written to diagnostic output. 
Status The following status values may be returned: 


0 No errors 
1 Syntax error (in parameters) 


Options None. 


Example StackWindows 


Stacks all of the Shell windows in a neat and orderly fashion. 


see also TileWindows, SizeWindow, ZoomWindow, and MoveWindow commands. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 


Tab—set a window’s tab value 
Tab number [ windows...] 


Sets the tab setting of the files in window to number spaces. If no windows are 
specified, the command operates on the target window (the second window from the 
front). It’s an error to specify a window that doesn’t exist. 


Note: The Tab command (and the Tabs menu item) modify the tab setting of an 
existing window. The {Tab} variable is used to initialize the tab setting of a new 
window, or as the default for files with no tab setting. 


Built-in. 

None. 

None. 

Errors are written to diagnostic output. 


Tab may return the following status values: 
QO No errors 


1 Syntax’ error 
2 An illegal tab count was specified 


None. 


Tab 4 
Sets the tab value of the target window to represent 4 spaces. 


Entab command. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 


Target—make a window the target window 
Target name 


Makes window name the target window for editing commands (that is, the second 
window from the front). If window name isn’t already open, then file name is opened 
as the target window. If name doesn’t exist, an error is returned. 


Built-in. 

None. 

None. 

Error messages are written to diagnostic output. 


The following status values may be returned: 


0 No errors 

1 Error in parameters 

2 ‘The specified file does not exist 
2, System error 

None. 


Target Sample.a 


Makes the window Sample.a the target window. 


Open command. 


“Editing With the Command Language” in Chapter 5. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 


TileWindows—arrange windows in tile pattern 


TileWindows 


Automatically sizes and moves all open Shell windows so that they are all visible on 


the screen at once. Arranging your open windows like tiles, and then zooming a 


selected window to full size, makes dealing with many open windows much easier. 


Built-in. 


None. 


None. 


Errors are written to diagnostic output. 


Tile Windows returns the following status values: 


0 No errors 
1 Syntax error (error in parameters) 


None. 


TileWindows 


Arranges all of the Shell windows in a tile pattern, so that all are visible. 


SizeWindow, ZoomWindow, StackWindows, and MoveWindow commands. 


TileWindows 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


TLACvt—convert Lisa TLA Assembler source 
TLACvt [ option...) [ sourceFile... | 


Converts the specified Lisa Workshop TLA Assembler source files to the syntax 
required by the MPW Assembler. If the input file name is name, the converted output 
is written to name.a. The following elements are converted: 


O tokens within statements 
O special tokens within macros 
Q directives 


For the details of these conversions, see “TLA Conversion” in Appendix E of the 
companion volume MPW Assembler 2.0 Reference. 


The case (upper/lower) of directive names in the output may be controlled by editing 
the file TLACvt.Directives. This file contains a list of all the MPW Assembler 
directives needed for conversion. The pathname to this file must be specified with 
the -f option. 


Tool. 
If no filenames are specified, standard input is converted. 


If input is from the standard input file, the converted output is written to standard 
output. If the input file name is mame, the converted output is written to name.a. You 
can use the -n, -prefix, and -suffix options to modify the output file naming 
conventions. 


Parameter errors and progress information are written to diagnostic output. 


The following status values may be returned: 


0 Normal termination 

1 Parameter or opuion error 

2 Execution terminated 

-d Detab the input. All tabs are removed and replaced with spaces. 


The number of spaces is determined by the tab setting. (See the 
-t option below.) 


-e Detab the input (as done by the -d option) and entab the output as a 
function of the tab setting. (See the -t option below.) 


-£ directivesFile The casing of directives is controlled by the file of directives 
specified by directivesFile. The file TLACvt.Directives is supplied 
for this purpose; you can edit it to change the capitalization. By 
default, all directives are converted to uppercase. 


-m Do not insert TLA-compatible mode-setting directives (BLANKS 
ON and STRING ASIS) into converted source. 
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Example 


Limitations 


See also 


-n Do not add the “*.a” extension to the input filename to produce the 
output filename. If you specify this option, you must also specify 
-prefix or -suffix. 


-p Writes TLACvt’s version information and conversion status to 
diagnostic output. 


-pre(fix] string If the input filename is Name, the output filename is produced by 
prefixing string to the name, that is, “stringName.a”. (The *.a” 
suffix may be suppressed by using the -n option or changed by using 
the -suffix option.) 


-suf(fix] string If the input filename is Name, the output filename is produced by 
appending string to the filename, that is, “Namestring’. The default 
suffix is “.a”. 


-t tabSetting Set the output file’s tab value to tabSetting (2 to 255). The default is 
to use the input file’s tab setting if there is one; otherwise a value 
of 8 is assumed. (8 is the default used by the Lisa Workshop’s 
MacCom utility when transferring text files—it’s assumed that 
MacCom was used to transfer the TLA files from the Lisa to the 
Macintosh.) 


uc When TLACvt detects a name in the opcode field that is the same as 
an MPW directive, it appends the character c to make the name 
unique. (The default character is #.) 


TLACvt -t 8 TLAFilel.Text TLAFile2.Text 


Converts the Lisa TLA Assembler source files TLAFile1.Text and TLAFile2.Text to the 
MPW Assembler source files TLAFile1.Text.a and TLAFile2.Text.a. The -t option sets 
the tab setting for both input files to 8, and entabs the output files based on a tab 
setting of 8. 


Limitations are noted in the detailed description of TLA conversions in the “PW 2.0 
Assembler Reference. 


CvtObj command. 
Appendix E, “TLA Conversion,” in the MPW Assembler 2.0 Reference. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Translate—convert selected characters 
Translate { options ] src{ ast] 


Standard input is copied to standard output, with input characters specified in the s7c 
(source) parameter string mapped into the corresponding characters specified by the 
dst (destination) parameter string; all other characters are copied as is. If dst is 
omitted, all characters represented by the src are deleted. If the dst string is shorter 
than the src, all characters in the src that would map to or beyond the last character in 
the dst are mapped into the last character in dst, and adjacent instances of such 
characters in the input are represented by a single instance of the last character in dst. 


Both src and dst are specified as a standard Shell character list but not enclosed in 
square brackets. Thus the src and dst are a sequence of one or more characters (that 
is, an abcde) or a range of characters separated by a minus sign (that is, a—z, 0-9). 
Standard escape characters (such as dt, dn, df) are processed by the Shell command 
interpreter. In order to specify a minus sign, place it last in the character list. Finally, 
the src character list may be preceded by a 7 to negate the list; that is, all characters 
except those in the src are taken as the src string. Thus they are all deleted if dst is 
absent, or collapsed if the last character in dst is present. 


Note: Case sensitivity of letters specified in the src list are governed by the 
{CaseSensitive} Shell variable. If CaseSensitive is set to 1, then only letters specified in 
the svc are mapped or deleted. If CaseSensitive is 0, then uppercase and lowercase 
letters not explicitly mapped into dst characters are mapped identically. 


Tool. 

All input is read from the standard input file. 

The translated input file is written to standard output. 
Errors are written to diagnostic output. 


Translate may return the following status values: 


0 Normal termination 
1 Parameter or option error 
2 Execution terminated 
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Options -p Write Translate’s version information to the diagnostic file. 


s Set the output file’s tab, font, and font size to the same as those of 
the input file’s. 


Translate Options 
{Input characters to translate Carresponifing output characters 


z 


CR aeecrcrte ee eden Se eee REE 


[] Progress 
CJ Set output font/tab 


Output Error 


Command Line 
Copies standard input to standard output with the substitution of specified ————— 
characters. (“Transiate —] 


Examples translate a-z A-Z <origFile >ucFile 


Converts all lowercase letters in origFile to uppercase and writes the translated file to 
ucFile. 


translate 0-9 9 <origFile >outFile 


Converts each string of digits in origFile to the single digit 9 in outFile. 


translate “ dtdn" dn <origFile >outFile 


Converts each run of blanks, tabs, or newline (return) characters in origFile to a single 
newline character in outFile. This effectively produces an output with just one word on 
each line. Note that the svc string had to be quoted to specify the blank. 


translate -a-zA-Zdn " " <origFile >outFile 


Removes all punctuation and isolates words by spaces on each line. Here we negated 
the src character list. Thus all characters except letters and newline characters are 
replaced with spaces. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 


Unalias—remove aliases 
Unalias [ mame... } 


Removes any alias definition associated with the alias name. (It is not an error if no 
definition exists for name.) 


Caution: If no names are specified, all aliases are removed. 


The scope of the Unalias command is limited to the current script, that is, aliases in 
enclosing scripts are not affected. If you are writing a script that is to be completely 
portable across various users’ configurations of MPW, you should place the 
command 


Unalias 

at the beginning of your script to make sure no unwanted substitutions occur. 
Built-in. 

None. 

None. 

None. 

A status value of 0 is always returned. 


None. 


Unalias File 


Remove the alias “File”. (This alias is defined in the Startup file.) 


Alias command. 


“Command Aliases” in Chapter 5. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 


See also 


Undo—undo last edit 


Undo [window } 


Undo is the scriptable equivalent of choosing Undo from the Edit menu to reverse the 
last editing operation. Undo without any parameters acts on the target (that is, the 


second from the front) window. Optionally a named window may be specified. 


Note: Remember that Undo is maintained on a window-by-window basis. Therefore 


using this command will undo the last edit operation that was performed in the 


specified window, which may or may not be the last operation actually performed. 


Built-in. 

None. 

None. 

Errors are written to diagnostic output 


Undo may return the following status values: 


0 No errors 
1 Syntax error (error in parameters) 
2 Any other error 


None. 


Undo 


Reverses the last edit operation in the target window. 


Undo "{Worksheet}" 


Reverses the last edit operation in the Worksheet window. 


Cut, Copy, and Paste commands. 


Undo 


I-197 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Unexport—remove a variable definition from export 


Unexport [-r | -s | name...] 


Removes the specified variables from the list of exported variables. The list of 
exported variables is local to a script, so unexported variables are removed only 
from the local list. 


If no names are specified, a list of unexported variables is written to standard output. 


The default output of Unexport is in the form of Unexport commands. (A variable 
that is not exported is considered unexported.) 


Built-in. 
None. 


If no names are given, Unexport writes a list of unexported variables to standard 
output 


Errors gre written to diagnostic output. 


Unexport may return the following status values: 


0 No error 
1 Syntax error 


-r Reverse the sense of the output, causing Unexport to generate 
Export commands for all unexported variables. 


-S Suppress the printing of “Unexport” before the unexported 
variables. 
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~~ 


Examples 


See also 


Set SrcDir "HD:source:" 
Export SrcDir # SrcDir is available to scripts and tools 


Unexport SrcDir 


Now the variable SrcDir is no longer available to scripts and tools. 


Unexport -r 
Export varl 
Export var2 


This example lists all the variables that are not exported. To export them, simply 
select and execute all the export commands. 


To get a list of all the variables that have not been exported, execute this command: 
Unexport -s 
varl 


var2 


Varx 


Set and Export commands. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 


Limitation 


See also 


Unmark—remove a marker from a file 
Unmark name... window 


Unmark removes the marker(s) name... ,from the list of markers available for 
window. When a window is the current active window, the Mark menu item(s) will be 
adjusted. 


Built-in. 

None. 

None. 

Errors and warnings are written to the diagnostic output. 


The following status values may be returned 


0 No errors 

1 Syntax error 

2 ‘Error in processing 

3 System error 

None. 

Unmark “Markers "{Target)" 


Removes all markers associated with the target window. 


Unmark Procl "{Active}" 


Removes the “Procl” marker from the active window’s marker list. Because {Active} 
is, by definition, the current active window, the Mark menu will also be adjusted to 
reflect the deletion of the “Proc1” marker. 


Unmark does not support Undo. 


“Markers” in Chapter 6. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 


See also 


Unmount—unmount volumes 
Unmount volume... 


Unmounts the specified volumes. A volume name must end with a colon (:). If 
volume is a number without a colon, it’s interpreted as a disk drive number. The 
unmounted volumes cannot be referenced again until remounted. If you unmount the 
current volume (the volume containing the current directory), then the boot volume 
becomes the current volume. 


Built-in. 

None. 

None. 

Error messages are written to diagnostic output. 


The following status values may be returned: 


0 The volume was successfully unmounted 
1 Syntax error 
2 An error occurred 


None. 


Unmount Memos: 


Unmounts the volume titted Memos. 


Unmeunt 1 2 


Unmounts the volumes in drives 1 (the internal drive) and 2 (the external drive). (The 
command Eject 1 2 would unmount and eject the volumes.) 


Eject and Mount commands. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Example 


See also 
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Unset—remove Shell variables 
Unset [ name... ] 


Removes any variable definition associated with name. (It’s not an error if no 
definition exists for name.) 


Caution: If no names are specified, all variable definitions are removed. This can 
have serious consequences. For example, the Shell uses the variable {Commands} to 
locate utilities and applications, and uses several other variables to set defaults. The 
Assembler and Compilers use variables to help locate include files. (For details, see 
“Variables Defined in the Startup File” in Chapter 5.) 


The scope of the Unset command is limited to the current script; that is, variables in 
enclosing scripts are not affected. 


Built-in. 

None. 

None. 

None. 

A status value of 0 is always returned. 
None. 


Unset CaseSensitive 


Removes the variable definition for {CaseSensitive}. This turns off case-sensitive 
searching for the editing commands. 


Set, Export, and Unexport commands. 
“Defining and Redefining Variables” in Chapter 5. 


Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Examples 


Volumes—list mounted volumes 
Volumes [-l] [-q] [ volume... ] 


For each volume named, Volumes writes its name and any other information 
requested to standard output. The output is sorted alphabetically. A volume name 
must end with a colon (:)—if volume is a number without a colon, it’s interpreted as a 
disk drive number. If volume is not given, all mounted volumes are listed. 


Built-in. 

None. 

Information about the specified volumes is written to standard output 
Error messages are written to diagnostic output. 


The following status values may be returned: 


0 No errors 
1 Syntax error 
2 No such volume 


-l List volumes in long format, giving volume name, drive (0 if 
offline), capacity, free space, number of files, and number of 
directories. 


-q Don’t quote volume names that contain special characters. (The 
default is to quote names that contain spaces or other special 
characters.) 


Volumes -l 
will write information such as 
Name Drive Size Free Files Dirs 


HD: 3 19171K 14242K 290 33 


Files ‘Volumes 1° 


Lists the files on the disk in drive 1 (the built-in 3.5-disk drive). 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Options 


Which—determine which file the Shell will execute 


Which [-a] [-p] [command] 


Determines which command the Shell will execute when command is entered. Which 
looks for commands defined by aliases, Shell built-in commands, and commands 
accessible through the Shell variable {Commands} (the same order the Shell uses). If 
command is not specified then all paths in the {Commands} variable will be written 
to standard output, one directory per line. The directories are listed in the order in 
which the Shell would search for commands. In this case the -a and -p options have no 
meaning. 


Built-in. 
None. 


In the case of a tool, application, or script, the full path of the command is written to 
standard output. If command is an alias its definition is written to standard output. If 
command is a built-in command then it is simply echoed back to standard output. 


Errors are written to diagnostic output. 


The following status values may be returned: 


0 No error 

dl Syntax error 

2 Command not found 
3 Other error 


-a All paths to command are written to standard output. This option 
allows the user to determine if there are multiple commands with 
the same name. 


-p Prints progress information as each directory in the variable 
commands is searched. 
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Examples Which asm 


This command outputs something like - HD:MPW:Tools:asm. The Shell then 
executes hd:MPW:Tools:asm when given asm. 


Which -a makeit 

Alias makeit ‘make > tmp; tmp' 
HD: MPW: Tools:makeit 
HD:MPW:Scripts:makeit 


In this case, there are three different “makeit” commands that the Shell could 
execute, as determined by current aliases and the {Commands} variable. The Shell 
executes the first one found (the alias). 


Which newfolder 
newfolder 


In this case, newfolder is a Shell built-in command. 
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Syntax 


Description 


Type 


Input 


Output 


Diagnostics 


Status 


Option 


Examples 


Windows—list windows 
Windows [-q] 


Writes the full pathname of each file currently in a window. The names are written to 
standard output, one per line, from backmost to frontmost. 


Built-in. 

None. 

The list of open windows is written to standard output. 
None. 

Status value 0 is always returned. 


-q Don't quote window names that contain special characters. (The 
default is to quote names that contain spaces or other special 
characters.) 


Windows 


Lists the pathnames of all open windows. 


Print (PrintOptions} ‘Windows’ 


Prints all of the open windows, using the options specified by the {PrintOptions} 
variable. This example uses command substitution: Because the Windows command 
appears in backquotes (...~), its output supplies the parameters to the Print 
command. 


Echo "Open “Windows’ || Set Status 0" > SavedWindows 


Writes a command script in the file SavedWindows that will reopen the current set of 
open windows. Notice how Echo is used to create the script. The conditional | | 
execution operator restores the status to zero should an error occur while opening the 
remembered windows. This technique is used in the Suspend script to save the list of 
open windows. 
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Syntax 


Description 


Type 


Output 


Diagnostics 


Status 


Option 


Examples 


See also 


ZoomWindow—enlarge or reduce a window 
ZoomWindow [ -s ] [window |] 


Zooms the specified window to full size on the screen. The default window is the 
target (second from the front) window; a specific window can optionally be 
specified. The -s option forces the window to zoom back to its small size. This 
capability is especially valuable when used in conjunction with StackWindows or 
TileWindows. 


Built-in. 
None. 
Errors are written to diagnostic output 


ZoomWindow may return the following status values: 


0 No errors 
1 Syntax error (error in parameters) 
Z The specified window does not exist 


-S Zoom the specified window back to its original, smaller size. 


ZoomWindow 


Zooms the target window to full size. 


ZoomWindow -s "“{Worksheet}" 


Zooms the Worksheet window back to its small size. 


SizeWindow, MoveWindow, StackWindows, and TileWindows commands. 


ZoomWindow 
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